---
title: "Customers"
permalink: "/docs/api-v1/customers"
description: "RevenueCat API v1 endpoint reference for Customers."
original_source: "openapi-spec/api-v1.yaml"
---
> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).
# Customers | REST API v1 Reference (1.0)
Download OpenAPI specification:[Download](https://www.revenuecat.com/docs/redocusaurus/openapi-v1-customers.yaml)
RevenueCat API v1 endpoint reference for Customers.
## Customers
Part of the [REST API v1 Reference](/docs/api-v1).
Operations about customers.
#### Endpoints
- [Get or Create Customer](#tag/customers/operation/subscribers) — `GET /subscribers/{app_user_id}`
- [Delete Customer](#tag/customers/operation/delete-subscriber) — `DELETE /subscribers/{app_user_id}`
- [Add Customer Attribution Data](#tag/customers/operation/subscribersattribution) — `POST /subscribers/{app_user_id}/attribution`
- [Update Customer Attributes](#tag/customers/operation/update-subscriber-attributes) — `POST /subscribers/{app_user_id}/attributes`
## Get or Create Customer
get/subscribers/{app_user_id}
https://api.revenuecat.com/v1/subscribers/{app_user_id}
Gets the latest [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the customer with the given App User ID, or creates a new customer if it doesn't exist.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID used with the mobile SDK.
##### header Parameters
- `X-Platform`: string Example: ios — Optionally set the X-Platform header to update the Customer's `last_seen` field. Set to either `ios`, `android`, `amazon`, `macos`, `uikitformac`. Don't set this if you are calling the getter for informational purposes or using a secret API key to fetch the customer's attributes.
### Responses
**200**
Success (customer found).
Returns the [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the Customer.
**201**
Success (customer created).
Returns the [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the Customer.
**400**
400
**401**
401
### Response samples
Content type
application/json
```json
{
"request_date": "2019-07-26T17:40:10Z",
"request_date_ms": 1564162810884,
"subscriber": {
"entitlements": {
"pro_cat": {
"expires_date": null,
"grace_period_expires_date": null,
"product_identifier": "onetime",
"purchase_date": "2019-04-05T21:52:45Z"
}
},
"first_seen": "2019-02-21T00:08:41Z",
"management_url": "https://apps.apple.com/account/subscriptions",
"non_subscriptions": {
"onetime": [
{
"id": "cadba0c81b",
"is_sandbox": true,
"purchase_date": "2019-04-05T21:52:45Z",
"store": "app_store"
}
]
},
"original_app_user_id": "XXX-XXXXX-XXXXX-XX",
"original_application_version": "1.0",
"original_purchase_date": "2019-01-30T23:54:10Z",
"other_purchases": { },
"subscriptions": {
"annual": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-14T21:07:40Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-07-14T20:07:40Z",
"refunded_at": null,
"store": "play_store",
"store_transaction_id": "GPA.6801-7988-0152-76034..5",
"unsubscribe_detected_at": "2019-07-17T22:48:38Z"
},
"onemonth": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-06-17T22:47:55Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-06-17T22:42:55Z",
"refunded_at": null,
"store": "app_store",
"store_transaction_id": 1000000652379790,
"unsubscribe_detected_at": "2019-06-17T22:48:38Z"
},
"rc_promo_pro_cat_monthly": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-26T01:02:16Z",
"grace_period_expires_date": null,
"is_sandbox": false,
"original_purchase_date": "2019-07-26T01:02:16Z",
"ownership_type": "FAMILY_SHARED",
"period_type": "normal",
"purchase_date": "2019-07-26T01:02:16Z",
"refunded_at": null,
"store": "promotional",
"store_transaction_id": "a42db3af39530cb82b17eaf9c6576393",
"unsubscribe_detected_at": null
}
}
}
}
```
## Delete Customer
delete/subscribers/{app_user_id}
https://api.revenuecat.com/v1/subscribers/{app_user_id}
Permanently deletes a customer.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID of the customer to be deleted (might be an aliased App User ID).
### Responses
**200**
Customer successfully deleted.
### Response samples
Content type
application/json
```json
{
"app_user_id": "XXX-XXXXX-XXXXX-XX",
"deleted": true
}
```
## Add Customer Attribution Data Deprecated
post/subscribers/{app_user_id}/attribution
https://api.revenuecat.com/v1/subscribers/{app_user_id}/attribution
Attaches attribution data to a subscriber from specific supported networks.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID of the Customer.
##### Request Body schema: application/json
- `data` (required): object — The data returned by the attribution network callbacks.
- `rc_idfa`: string — The idfa from AdSupport on iOS. (iOS Only)
- `rc_gps_adid`: string — The Google Play Services Advertising identifier. (Android Only)
- `network` (required): string Enum: "0" "1" "2" "3" "4" "5" — The attribution network the data is coming from: * 0: Apple Search AdSupport * 1: Adjust * 2: AppsFlyer * 3: Branch * 4: Tenjin * 5: Facebook
### Responses
**200**
Attribution data was successfully posted.
### Request samples
Content type
application/json
```json
{
"data": {
"rc_idfa": "string",
"rc_gps_adid": "string"
},
"network": "0"
}
```
### Response samples
Content type
application/json
```json
"{}"
```
## Update Customer Attributes
post/subscribers/{app_user_id}/attributes
https://api.revenuecat.com/v1/subscribers/{app_user_id}/attributes
Updates attributes for a customer.
##### Authorizations:
_BearerAuth_
##### path Parameters
- `app_user_id` (required): string — The App User ID used with the mobile SDK.
##### Request Body schema: application/json
- `attributes`: object
- `key_name` (required): object — Mapping of keys to attribute values.
- `value` (required): string — The value of the attribute. If the value is `null` or an empty string, the attribute will be deleted.
- `updated_at_ms`: integer `int64` — UNIX epoch in milliseconds of when the attribute was updated. This value is used to resolve conflicts, an attribute will only be updated if the new `updated_at_ms` value is newer than the value for the stored attribute.
### Responses
**200**
Attributes were successfully updated.
Returns the updated [Customer Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the Customer.
**400**
400
### Request samples
Content type
application/json
```json
{
"attributes": {
"key_name": {
"value": "string",
"updated_at_ms": 1709195668093
}
}
}
```
### Response samples
Content type
application/json
```json
{
"value": {
"request_date": "2019-07-26T17:40:10Z",
"request_date_ms": 1564162810884,
"subscriber": {
"entitlements": {
"pro_cat": {
"expires_date": null,
"grace_period_expires_date": null,
"product_identifier": "onetime",
"purchase_date": "2019-04-05T21:52:45Z"
}
},
"first_seen": "2019-02-21T00:08:41Z",
"management_url": "https://apps.apple.com/account/subscriptions",
"non_subscriptions": {
"onetime": [
{
"id": "cadba0c81b",
"is_sandbox": true,
"purchase_date": "2019-04-05T21:52:45Z",
"store": "app_store"
}
]
},
"original_app_user_id": "XXX-XXXXX-XXXXX-XX",
"original_application_version": "1.0",
"original_purchase_date": "2019-01-30T23:54:10Z",
"other_purchases": { },
"subscriptions": {
"annual": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-14T21:07:40Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-07-14T20:07:40Z",
"refunded_at": null,
"store": "play_store",
"store_transaction_id": "GPA.6801-7988-0152-76034..5",
"unsubscribe_detected_at": "2019-07-17T22:48:38Z"
},
"onemonth": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-06-17T22:47:55Z",
"grace_period_expires_date": null,
"is_sandbox": true,
"original_purchase_date": "2019-02-21T00:42:05Z",
"ownership_type": "PURCHASED",
"period_type": "normal",
"purchase_date": "2019-06-17T22:42:55Z",
"refunded_at": null,
"store": "app_store",
"store_transaction_id": 1000000652379790,
"unsubscribe_detected_at": "2019-06-17T22:48:38Z"
},
"rc_promo_pro_cat_monthly": {
"auto_resume_date": null,
"billing_issues_detected_at": null,
"expires_date": "2019-08-26T01:02:16Z",
"grace_period_expires_date": null,
"is_sandbox": false,
"original_purchase_date": "2019-07-26T01:02:16Z",
"ownership_type": "FAMILY_SHARED",
"period_type": "normal",
"purchase_date": "2019-07-26T01:02:16Z",
"refunded_at": null,
"store": "promotional",
"store_transaction_id": "a42db3af39530cb82b17eaf9c6576393",
"unsubscribe_detected_at": null
}
}
}
}
}
```
## Endpoint Reference
All API v1 resources, one page each. General concepts (authentication, request format, URL parameters) live on the [API v1 overview](/docs/api-v1).
- [Customer Info Model](/docs/api-v1/customer-info-model) — full schema reference
- [Customers](/docs/api-v1/customers) — 4 endpoints
- [Entitlements](/docs/api-v1/entitlements) — 2 endpoints
- [Offerings](/docs/api-v1/offerings) — 3 endpoints
- [Offerings Model](/docs/api-v1/offerings-model) — full schema reference
- [Transactions](/docs/api-v1/transactions) — 6 endpoints
## Response schema reference
Response examples above mirror the rendered API reference. These field definitions come from the same OpenAPI specification.
### Subscriber
- Used by `GET /subscribers/{app_user_id} (200) — Get or Create Customer`
- Used by `POST /subscribers/{app_user_id}/attributes (200) — Update Customer Attributes`
- `request_date`: string — Date of the request in ISO 8601 format.
- `request_date_ms`: integer (format: `int64`) — Date of the request in milliseconds since Epoch.
- `subscriber`: object — Information about the Customer.
- `entitlements`: object — Dictionary of the entitlements of this Customer (including any expired entitlements).
- `first_seen`: string — The ISO 8601 datetime string corresponding to when the Customer was first seen by RevenueCat.
- `last_seen`: string — The ISO 8601 datetime string corresponding to when the Customer was last seen by RevenueCat.
- `management_url`: string — URL to manage the active subscription of the Customer. If the Customer has an active App Store subscription, this will point to the App Store. If the Customer has an active Play Store subscription, it will point there. Amazon subscriptions point to the Amazon subscription management page, Paddle subscriptions point to the Paddle Customer Portal, and RevenueCat Web Billing subscriptions point to the RevenueCat Web Billing Customer Portal. For Stripe Billing subscriptions, this returns the configured Stripe Customer Portal URL or a custom URL. If no Stripe Customer Portal URL is configured, this will be null. If there are no active subscriptions it will be null. If the Customer has multiple active subscriptions for different platforms, this will take the value of the OS in the `X-Platform` header into consideration: - If the request was made on an OS for which there are active subscriptions, this will return the URL for the store that matches the header. - If the request was made on a different OS or the OS was not included in the X-Platform header, this will return the URL for the store of the subscription with the farthest future expiration date.
- `non_subscriptions`: object — Non-subscription purchases of the Customer, keyed by the product identifier.
- `original_app_user_id`: string — The App User ID under which this Customer was first known to RevenueCat.
- `original_application_version`: string — *Only available on iOS*. This will be `null` until an iOS receipt is sent for the Customer. After a receipt has been sent, it will indicate the first App Store version of your app that the Customer installed.
- `original_purchase_date`: string — **Only available on iOS**. The date that the app was first purchased/downloaded by the Customer. Will be `null` if no receipt is recorded for the Customer. Useful for [Migrating Subscriptions](/docs/migrating-to-revenuecat/migrating-existing-subscriptions).
- `other_purchases`: object
- `subscriber_attributes`: object — A dictionary of any Attributes set on this Customer. **Only included in responses to requests made with a secret API key**.
- `subscriptions`: object — Subscription purchases of the Customer, keyed by the product identifier.
### Delete Customer response
- Used by `DELETE /subscribers/{app_user_id} (200) — Delete Customer`
- `app_user_id` (required): string — The App User ID of the customer that was requested to be deleted
- `deleted` (required): boolean — Whether or not the customer was successfully deleted
### Add Customer Attribution Data response
- Used by `POST /subscribers/{app_user_id}/attribution (200) — Add Customer Attribution Data`
- Response type: object