- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
-
Order Ahead
-
Getting Started
-
Endpoints
-
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
- Orders
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
List Past Orders
Order Ahead / Endpoints
List Past Orders
This endpoint allows you to get the order history for a user.
Request Endpoint
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.