List Past Orders

Order Ahead / Endpoints

List Past Orders

This endpoint allows you to get the order history for a user.

Request Endpoint

GET /v15/users/orders

To see a user’s orders, you must have a user access token with the read_user_orders permission.

Pagination

The response is paginated, and the “Link” header in the API response contains the URL for the next page of results. When a call returns a 204 No Content response, the client knows that they have reached the current end of results.

Authorization Required – User Token in Header

Authorization: token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"

cURL Example

curl https://sandbox.thelevelup.com/v15/users/orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization:token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"'

Example Response

[{
    "order": {
        "bundle_closed_at": "2015-01-22T13:54:09-05:00",
        "bundle_descriptor": "LevelUp*SampleMerchant",
        "contribution_target_name": null,
        "created_at": "2015-01-22T13:54:07-05:00",
        "identifier_from_merchant": "001001",
        "location_id": 19,
        "location_extended_address": "",
        "location_locality": "Boston",
        "location_name": "",
        "location_postal_code": "02114",
        "location_region": "Massachusetts",
        "location_street_address": "1234 Test Street",
        "merchant_id": 34,
        "merchant_name": "SampleMerchant",
        "pos_app_id": 123,
        "refunded_at": null,
        "transacted_at": "2015-01-22T13:54:07-05:00",
        "uuid": "f7943600849501323c1552668b2aa48c",
        "balance_amount": 997,
        "contribution_amount": 0,
        "credit_applied_amount": 0,
        "credit_earned_amount": 0,
        "spend_amount": 997,
        "tax_amount": 30,
        "tip_amount": 0,
        "total_amount": 997
    }
}, {
    "order": {
        "bundle_closed_at": "2015-01-22T11:29:24-05:00",
        "bundle_descriptor": "LevelUp*SampleMerchant",
        "contribution_target_name": null,
        "created_at": "2015-01-22T11:29:22-05:00",
        "identifier_from_merchant": "10011234",
        "location_id": 19,
        "location_extended_address": "",
        "location_locality": "Boston",
        "location_name": "",
        "location_postal_code": "02114",
        "location_region": "Massachusetts",
        "location_street_address": "1234 Test Street",
        "merchant_id": 34,
        "merchant_name": "SampleMerchant",
        "pos_app_id": 123,
        "refunded_at": "2015-01-22T14:28:05-05:00",
        "transacted_at": "2015-01-22T11:29:22-05:00",
        "uuid": "bf143c9084810132faf95a123bd6cde9",
        "balance_amount": 10,
        "contribution_amount": 0,
        "credit_applied_amount": 0,
        "credit_earned_amount": 0,
        "spend_amount": 10,
        "tax_amount": 3,
        "tip_amount": 0,
        "total_amount": 10
    }
}, {
    "order": {
        "bundle_closed_at": "2015-01-21T14:20:27-05:00",
        "bundle_descriptor": "LevelUp*SampleMerchant",
        "contribution_target_name": null,
        "created_at": "2015-01-21T14:20:26-05:00",
        "identifier_from_merchant": "001001",
        "location_id": 19,
        "location_extended_address": "",
        "location_locality": "Boston",
        "location_name": "",
        "location_postal_code": "02114",
        "location_region": "Massachusetts",
        "location_street_address": "1234 Test Street",
        "merchant_id": 34,
        "merchant_name": "SampleMerchant",
        "pos_app_id": 123,
        "refunded_at": null,
        "transacted_at": "2015-01-21T14:20:26-05:00",
        "uuid": "7a223f5083d001322c2a5a56e9bb8aab",
        "balance_amount": 997,
        "contribution_amount": 0,
        "credit_applied_amount": 0,
        "credit_earned_amount": 0,
        "spend_amount": 997,
        "tax_amount": 30,
        "tip_amount": 0,
        "total_amount": 997
    }
}]
  ...
]

Response Parameters

Param Type Description
bundle_closed_at String (Date) or null The time the bundle containing this order closed (or null if it’s still open).
bundle_descriptor String The the descriptor (or the best guess at) that this order will show up as on the user’s payment statement.
contribution_target_name String or null The name of the user’s chosen contribution target.
created_at String (Date) The ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) the order was created. See transacted_at for the date and time the order was placed.
identifer_from_merchant String The POS-specific order ID or number for the check. Max 255 characters.
location_id Integer The ID of the location at which the order was placed.
location_extended_address String or null The extended street address (suite or unit number, etc.) of the location at which the order was placed.
location_locality String The locality (i.e. city) of the location at which the order was placed.
location_name String The nickname or alternate name for the location at which the order was placed.
location_postal_code String The postal code of the location at which the order was placed.
location_region String The region (i.e. state) of the location at which the order was placed.
location_street_address String The street address of the location at which the order was placed.
merchant_id Integer The ID of the merchant at which the order was placed.
merchant_name String The name of the merchant at which the order was placed.
pos_app_id Integer The ID of the requesting app that was used to place the order.
refunded_at String (Date) or null The ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) the order was refunded.
transacted_at String The ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) the user placed the order.
uuid String (UUID) The order’s unique identifier.
balance_amount Integer (Money) The amount (in cents) charged to the user’s credit card.
contribution_amount Integer (Money) or null The amount (in cents) contributed to the user’s chosen contribution target.
credit_applied_amount Integer (Money) The amount (in cents) of all credit used to fund the order.
credit_earned_amount Integer (Money) The amount (in cents) of all credit earned from the order.
spend_amount Integer (Money) The amount (in cents) spent by the user, excluding tip and credit applied.
tax_amount Integer (Money) The tax amount in cents (or null if it’s 0).
tip_amount Integer (Money) The amount (in cents) tipped by the user.
total_amount Integer (Money) The amount (in cents) spent by the user, including tip, but excluding credit applied.

Response Headers

Header Description
Link The URL to use for requesting the next page of results.

List more orders

To keep this example simple, assume that each page of results only includes 2 orders. Fields other than bundle_closed_at are hidden. Response headers other than “Link” are also not shown.

For the very first page of results, the client simply requests /users/orders.

Request: https://api.thelevelup.com/v15/users/orders

Response Headers:

Link: <https://api.thelevelup.com/v15/users/orders?page=2>; rel="next"

Status Code: 200 OK

Body:

[
  {
    "order": {
      "bundle_closed_at": null,
      ...
    }
  },
  {
    "order": {
      "bundle_closed_at": null,
      ...
    }
  }
]

The client remembers the value of the “Link” header, and uses it to retrieve the next page of results:

Request: https://api.thelevelup.com/v15/users/orders?page=2

Response Headers:

Link: <https://api.thelevelup.com/v15/users/orders?page=3>; rel="next"

Status Code: 200 OK

Body:

[
  {
    "order": {
      "bundle_closed_at": null,
      ...
    }
  },
  {
    "order": {
      "bundle_closed_at": null,
      ...
    }
  }
]

Finally the next (and currently last) page of results:

Request: https://api.thelevelup.com/v15/users/orders?page=20

Response Headers: (Does not include a Link header.)

Status Code: 204 No Content

Body: (empty)

Since the client got a 204 No Content response, it knows that it is done retrieving updates.