Skip to main content
Skip to navigation
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Customer

Part of the REST API v2 Reference. More Customer endpoints: Customer Resources.

Operations about customers.

Endpoints

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": {
    }
}

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
}

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": {
    }
}

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
{}

Grant an entitlement to a customer

Grants a promotional entitlement until expires_at, and creates a promotional subscription, but only if expires_at is at least two hours away from any existing promotional grant for the same entitlement.

To extend access, call again with a new expires_at that is at least two hours later than the existing grant. To shorten access, revoke the existing grant, then grant again with the desired expires_at. For store billing-period extensions, use /subscriptions/{subscription_id}/actions/extend (Apple, Google Play, and Web Billing only). 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>

Expiry in milliseconds since epoch (must be in the future). If another promotional grant for this entitlement already has an expiry within two hours of this value, the request is ignored as a duplicate.

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": {
    }
}

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": {
    }
}

Revoke a granted entitlement from a customer

Revokes all active promotional grants of this entitlement. Associated promotional subscriptions are expired and access ends immediately. 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": {
    }
}

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": {
    }
}

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"
}

Endpoint Reference

All API v2 resources, one page each. General concepts (authentication, pagination, rate limits, error handling) live on the API v2 overview.