Skip to main content
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Customer

Operations about customers.

List or search customers

This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
starting_after
string
Example: starting_after=ent12354

Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page.

limit
integer
Default: 20
Example: limit=10

Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected.

search
string [ 1 .. 255 ] characters
Example: search=example@example.com

Search term used to find matching customers within the project. The term is matched against, in order: the $email attribute (exact match), the customer's app user IDs, store transaction identifiers (Apple, Google Play and Amazon), and Apple order IDs. Email searches are paginated; all other identifier searches return a single page of matches.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/projec1a2b3c4d/customers?starting_after=223xx1100",
  • "url": "/v2/projects/projec1a2b3c4d/customers"
}

Create a customer

This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

Request Body schema: application/json
required
id
required
string [ 1 .. 1500 ] characters ^[0-9a-zA-Z_-]*$

The ID of the customer

Array of objects <= 50 characters
Array
required
CustomerAttributeReservedName (string) or CustomerAttributeCustomName (string) [ 1 .. 40 ] characters

The name of the attribute

value
required
string <= 500 characters

The value of the attribute

Responses

Request samples

Content type
application/json
{
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "last_seen_app_version": "1.0.0",
  • "last_seen_country": "US",
  • "last_seen_platform": "android",
  • "last_seen_platform_version": "35",
  • "active_entitlements": {
    },
  • "experiment": {
    },
  • "attributes": {
    }
}

Get a customer

This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
expand
Array of strings[ items [ 1 .. 5000 ] characters ]
Items Value: "attributes"
Example: expand=attributes

Specifies which fields in the response should be expanded. Accepted values are: attributes (requires customer_information:customers:read permission).

Responses

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "last_seen_app_version": "1.0.0",
  • "last_seen_country": "US",
  • "last_seen_platform": "android",
  • "last_seen_platform_version": "35",
  • "active_entitlements": {
    },
  • "experiment": {
    },
  • "attributes": {
    }
}

Delete a customer

This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Responses

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "b5b7bfd2-66fb-4091-af50-7c3cdccfdf24",
  • "deleted_at": 1658399423658
}

Transfer customer's subscriptions and one-time purchases to another customer

This endpoint requires the following permission(s): customer_information:customers:read_write, customer_information:subscriptions:read_write, customer_information:purchases:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
target_customer_id
required
string

The ID of the customer to whom the subscriptions and one-time purchases will be transferred.

app_ids
Array of strings or null[ items [ 1 .. 255 ] characters ]

Optional. The IDs of the apps to filter the transfer by. When specified, only purchases and subscriptions associated with these apps will be transferred.

Responses

Request samples

Content type
application/json
{
  • "target_customer_id": "string",
  • "app_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "source_customer": {
    },
  • "target_customer": {
    }
}

Grant an entitlement to a customer

Grants an entitlement to a customer unless one already exists. As a side effect, a promotional subscription is created. This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
entitlement_id
required
string [ 1 .. 255 ] characters

The ID of the entitlement to grant to the customer.

expires_at
required
integer <int64>

The date after which the access to the entitlement expires in ms since epoch.

Responses

Request samples

Content type
application/json
{
  • "entitlement_id": "entla1b2c3d4e5",
  • "expires_at": 1658399423658
}

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "last_seen_app_version": "1.0.0",
  • "last_seen_country": "US",
  • "last_seen_platform": "android",
  • "last_seen_platform_version": "35",
  • "active_entitlements": {
    },
  • "experiment": {
    },
  • "attributes": {
    }
}

Revoke a granted entitlement from a customer

Revokes a granted entitlement from a customer. As a side effect, the promotional subscription associated with the granted entitlement is expired. This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
entitlement_id
required
string [ 1 .. 255 ] characters

The ID of the granted entitlement to revoke from the customer.

Responses

Request samples

Content type
application/json
{
  • "entitlement_id": "entla1b2c3d4e5"
}

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "last_seen_app_version": "1.0.0",
  • "last_seen_country": "US",
  • "last_seen_platform": "android",
  • "last_seen_platform_version": "35",
  • "active_entitlements": {
    },
  • "experiment": {
    },
  • "attributes": {
    }
}

Assign or clear an offering override for a customer

This endpoint requires the following permission(s): project_configuration:offerings:read, customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
offering_id
required
string or null [ 1 .. 255 ] characters

The ID of the offering to assign to the customer. Set to null to clear any existing override.

Responses

Request samples

Content type
application/json
{
  • "offering_id": "offrng1b2c3d4e5"
}

Response samples

Content type
application/json
Example
{}

Restore a Google Play purchase by order ID

Restores a Google Play purchase to the specified customer using a Google Play order ID. This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
order_id
required
string non-empty

The Google Play order ID to restore.

Responses

Request samples

Content type
application/json
{
  • "order_id": "GPA.1234-5678-9012-34567"
}

Response samples

Content type
application/json
{
  • "object": "customer",
  • "id": "19b8de26-77c1-49f1-aa18-019a391603e2",
  • "project_id": "proj1ab2c3d4",
  • "first_seen_at": 1658399423658,
  • "last_seen_at": 1658399423658,
  • "last_seen_app_version": "1.0.0",
  • "last_seen_country": "US",
  • "last_seen_platform": "android",
  • "last_seen_platform_version": "35",
  • "active_entitlements": {
    },
  • "experiment": {
    },
  • "attributes": {
    }
}

Get a list of the customer's aliases

This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
starting_after
string
Example: starting_after=ent12354

Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page.

limit
integer
Default: 20
Example: limit=10

Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/aliases?starting_after=9fjeja8fjed",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/aliases"
}

Get a list of the customer's attributes

This endpoint requires the following permission(s): customer_information:customers:read. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

query Parameters
starting_after
string
Example: starting_after=ent12354

Pagination cursor. Pass the id of the last item from the previous page to fetch the next page; omit for the first page.

limit
integer
Default: 20
Example: limit=10

Maximum number of items to return per page. Values below 1 or above 100 are clamped to that range rather than rejected.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/attributes?starting_after=myCustomAttribute",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/attributes"
}

Set a customer's attributes

This endpoint requires the following permission(s): customer_information:customers:read_write. This endpoint belongs to the Customer Information domain, which has a default rate limit of 480 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

customer_id
required
string [ 1 .. 1500 ] characters
Example: 19b8de26-77c1-49f1-aa18-019a391603e2

ID of the customer

Request Body schema: application/json
required
required
Array of objects [ 1 .. 50 ] items
Array ([ 1 .. 50 ] items)
required
CustomerAttributeReservedName (string) or CustomerAttributeCustomName (string) [ 1 .. 40 ] characters

The name of the attribute

value
required
string or null <= 500 characters

The value of the attribute. Use null to delete the attribute.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "list",
  • "items": [
    ],
  • "next_page": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/attributes?starting_after=myCustomAttribute",
  • "url": "/v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/attributes"
}