Success responses

When a request is successful, Paddle returns a data object or array with a 2xx HTTP response code. List endpoints return a data array and metadata object with pagination information.

The Paddle API always returns requested entities in a data object or array. In most cases, it also returns a meta object with information about the request, including pagination information for list operations.

Success responses return a 2xx response code.

When there's an error, the API returns an error object instead. Errors return a 4xx or 5xx response code.

Get an entity

When you successfully get an entity, Paddle returns:

A data object with the requested entity.
A meta object with information about the request.

The response code is 200.

GEThttps://api.paddle.com/customers/{customer_id}

customer_idstring

Paddle ID of the customer to get.

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "data": {
3    "id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
4    "status": "active",
5    "custom_data": null,
6    "name": "Sam Miller",
7    "email": "sam@example.com",
8    "marketing_consent": false,
9    "locale": "en",
10    "created_at": "2024-03-08T16:49:53.691Z",
11    "updated_at": "2024-04-11T16:03:57.924146Z",
12    "import_meta": null
13  },
14  "meta": {
15    "request_id": "aa0009cb-18f7-4538-b1cd-ad29d91cfaa7"
16  }
17}

List entities

When you successfully list entities, Paddle returns:

A data array that includes a paginated list of requested entities.
A meta object that includes pagination information.

The response code is 200.

GEThttps://api.paddle.com/customers

GET https://api.paddle.com/customers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": [
3    {
4      "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
5      "status": "active",
6      "custom_data": null,
7      "name": "Jo Brown-Anderson",
8      "email": "jo@example.com",
9      "marketing_consent": false,
10      "locale": "en",
11      "created_at": "2024-04-11T15:57:24.813Z",
12      "updated_at": "2024-04-11T15:59:56.658719Z",
13      "import_meta": null
14    },
15    {
16      "id": "ctm_01h844q4mznqpgqgm6evgw1w63",
17      "status": "active",
18      "custom_data": null,
19      "name": "Jamie Price",
20      "email": "jamie@example.com",

Create an entity

When you successfully create an entity, Paddle returns:

A data object with the created entity.
A meta object with information about the request.

All the fields against the new entity are returned, including any generated or calculated fields. If you omitted optional fields, Paddle returns those with the default values.

The response code is 201.

Request

POSThttps://api.paddle.com/customers

This example creates a customer with only the required fields.

POST https://api.paddle.com/customer

1
2
3
4
1{
2  "email": "jo@example.com",
3  "name": "Jo Brown"
4}

Response

Paddle returns the new entity with all fields, not just those you included in your request. Generated fields, like the Paddle ID, are included.

201 Created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "data": {
3    "id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
4    "status": "active",
5    "custom_data": null,
6    "name": "Jo Brown",
7    "email": "jo@example.com",
8    "marketing_consent": false,
9    "locale": "en",
10    "created_at": "2024-04-11T15:57:24.813Z",
11    "updated_at": "2024-04-11T15:57:24.813Z",
12    "import_meta": null
13  },
14  "meta": {
15    "request_id": "9bcdcc29-e180-4055-ad3d-d37e5dc5e56d"
16  }
17}

Update an entity

When you successfully update an entity, Paddle returns:

A data object with the updated entity.
A meta object with information about the request.

All the fields against the updated entity are returned, including fields that you didn't change.

The response code is 200.

Request

This example archives a customer by changing the status field to archived.

PATCHhttps://api.paddle.com/customers/{customer_id}

customer_idstring

Paddle ID of the customer to update.

PATCH api.paddle.com/customers/ctm_01hrffh7gvp29kc7xahm8wddwa

1
2
3
1{
2  "status": "archived"
3}

Response

Paddle returns the updated entity with all fields, not just those you included in your request.

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "data": {
3    "id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
4    "status": "archived",
5    "custom_data": null,
6    "name": "Sam Miller",
7    "email": "sam@example.com",
8    "marketing_consent": false,
9    "locale": "en",
10    "created_at": "2024-03-08T16:49:53.691Z",
11    "updated_at": "2024-04-11T16:03:57.924146Z",
12    "import_meta": null
13  },
14  "meta": {
15    "request_id": "aa0009cb-18f7-4538-b1cd-ad29d91cfaa7"
16  }
17}

Errors

Pagination

Paddle IDs