- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
- Order Ahead
-
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
-
-
Orders .: List by App
API Reference / v15
List Orders Placed Using a Specific App
This endpoint returns a list of orders placed by the current user through the requesting app. The response includes user-oriented data, as opposed to merchant-oriented data. If the app is considered “global”, this endpoint returns all orders placed at any merchant through the requesting app. To list orders by app for a user, you must have a user access token with the read_user_orders
permission. 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.
Request Endpoint
Authorization Required – User Token in Header
Authorization: token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"
Request Parameters
Param | Type | Required | Description |
---|---|---|---|
page |
Integer or null | No | Page number of results to return. |
cURL Example
curl https://sandbox.thelevelup.com/v15/apps/orders \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization:token user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"'
Example Response
HTTP/1.1 200 OK
[
{
"order": {
"bundle_closed_at": null,
"bundle_descriptor": "LevelUp*NedsFalafel",
"contribution_target_name": null,
"created_at": "2014-05-05T12:33:41-04:00",
"identifier_from_merchant": "100010",
"location_id": 3796,
"location_extended_address": "Ste 400",
"location_locality": "Boston",
"location_postal_code": "02110",
"location_region": "MA",
"location_street_address": "1234 Main St",
"merchant_id": 1234,
"merchant_name": "Ned's Falafel Shop",
"refunded_at": null,
"transacted_at": "2014-05-05T12:33:41-04:00",
"uuid": "a209dd40b6a001318b26125276c82bfa",
"balance_amount": 0,
"contribution_amount": null,
"credit_applied_amount": 10,
"credit_earned_amount": 0,
"spend_amount": 10,
"tip_amount": 0,
"total_amount": 10
}
},
...
]
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. |
identifier_from_merchant |
String | The POS-specific order identifier (usually the check ID #) for the order. |
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_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. |
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. |
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 /v15/apps/orders
.
Request: https://api.thelevelup.com/v15/apps/orders
Response Headers:
Link: <https://api.thelevelup.com/v15/apps/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/apps/orders?page=2
Response Headers:
Link: <https://api.thelevelup.com/v15/apps/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/apps/orders?page=20
Response Headers: (Does not include a Link header.)
Status Code: 204 No Content
Body: (empty)
Since the client got a 204 response, it knows that it is done retrieving updates.