Data Conventions#

Dates and times#

All timestamps are ISO 8601 with timezone information, for example 2014-02-27T15:05:06.123Z.

Endpoints that accept a date (not a datetime) expect the format YYYY-MM-DD, for example 2014-02-27.

Cursor pagination#

All list endpoints are ordered and paginated reverse-chronologically by default.

Request parameters#

Parameter	Description
`before`	ID of the object immediately following the array to be returned.
`after`	ID of the object immediately preceding the array to be returned.
`limit`	Maximum number of objects to return. Default `50`, max `500`, min `1`.

Response metadata#

Every paginated response includes a meta.cursors object:

Field	Description
`before`	ID of the first resource returned.
`after`	ID of the last resource returned.
`limit`	Upper bound applied. May be less than requested if fewer objects exist.

Example#

GET https://api.gocardless.com/payments?after=ID789 HTTP/1.1
 
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "payments": [
    { "id": "PM0001", "amount": 1000, "currency": "GBP" },
    { "id": "PM0002", "amount": 2000, "currency": "GBP" }
  ],
  "meta": {
    "cursors": {
      "before": "PM0001",
      "after":  "PM0002"
    },
    "limit": 50
  }
}

What's next#

Responses and Errors

HTTP response codes and how to handle each error type.

Learn more

Making Requests

Authentication, headers, and how to structure every API call.

Learn more