Orders

You can use the orders API to view, create and update orders in LoyaltyLion. This is necessary if you want to award points for placing orders.

GET /v2/orders

Returns a list of orders in LoyaltyLion.

Request

You can pass the following query parameters with the request, all of which are optional.

ParamDescription
since_idReturn only orders whose id is after the specified id
limitNumber of orders to return per request. Must be between 1-500 (default: 100)
pagePage to show (default: 1)
created_at_minReturn only orders created after this date (ISO8601 format)
created_at_maxReturn only orders created before this date (ISO8601 format)
updated_at_minReturn only orders last updated after this date (ISO8601 format)
updated_at_maxReturn only orders last updated before this date (ISO8601 format)

Response

This endpoint will return a list of order resources.

FieldTypeDescription
idintegerUnique id of the order in LoyaltyLion
merchant_idstringUnique id of order in your store
merchant_numberstringIf applicable, a human readable order number in your store
totalstringOrder total, after shipping and tax, before discounts (e.g. ‘99.95’)
total_taxstringTotal tax (e.g. ‘0.50’)
total_shippingstringTotal shipping (e.g. ‘2.50’)
total_discountsstringTotal discounts (e.g. ‘5.00’)
total_paidstringTotal paid (e.g. ‘50.00’)
total_refundedstringTotal refunded (e.g. ‘25.50’)
payment_statusstringOne of paid , partially_paid and not_paid
fulfillment_statusstringOne of fulfilled , partially_fulfilled and not_fulfilled
refund_statusstringOne of refunded , partially_refunded and not_refunded
cancellation_statusstringOne of cancelled , not_cancelled
customerobjectAn object containing the linked customer’s id and other fields
metadataobjectDepending on your platform, this may include platform specific metadata
created_atstringAn ISO8601 timestamp representing when this order was created in LoyaltyLion
updated_atstringAn ISO8601 timestamp representing when this order was last updated in LoyaltyLion

Example

curl \
  --url 'https://api.loyaltylion.com/v2/orders?since_id=500' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

POST /v2/orders

Use this endpoint to track a new order in LoyaltyLion.

Request

Order totals

Currency values can be provided as strings (“19.95”) or numeric values (19.95). You should send amounts as the currency you have selected as your primary currency in LoyaltyLion.

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
customer_idstringyesUnique ID for the customer who placed this order. This should be your internal ID for this customer
customer_emailstringyesThe email address for the customer who placed this order
merchant_idstringyesUnique ID your system uses to refer to this order. You’ll use this ID to update this order later
totalstringyesOrder total, after shipping and tax, before discounts (e.g. ‘99.95’)
total_shippingstringyesTotal shipping cost for the order
payment_statusstringyesThe payment status of this order. Must be one of: not_paid , partially_paid and paid
total_paidstringsometimesThe total amount that has been paid for this order. This is required if the order’s payment status is partially_paid - otherwise it will default to 0.00 (for not_paid orders) or the order’s total (for paid orders)
merchant_numberstringnoHuman-readable ID for this order. If supplied, we’ll show this order in the LoyaltyLion admin using this instead of its merchant_id
discount_codesarraynoAn array of discount code objects (see below). We’ll use this to track when LoyaltyLion discount rewards have been used
claimed_reward_idsarraynoAn array of claimed reward IDs. We’ll use this to track when LoyaltyLion rewards have been used with an order
datestringnoThe date this order was placed, as an ISO8601 timestamp. Will default to now if not provided
ip_addressstringnoThe IP address of the customer who placed this order. Used in combination with user_agent to track referrals
user_agentstringnoThe full user agent string of the customer who placed this order. Used in combination with ip_address to track referrals
referral_idstringnoA LoyaltyLion referral ID - more details
tracking_idstringnoA LoyaltyLion email tracking ID - more details
guestbooleannoA boolean value indicating if the customer who placed this order is a guest. The default is false.

Discount code object

FieldTypeRequiredDescription
codestringyesThe discount code as entered by the customer, e.g. “AUEX-8Q7L”
amountstringyesThe discount provided, e.g. 5.00

Response

Returns a 201 Created response if the order was created successfully. If the order was invalid, a 422 Unprocessable Entity response will be returned.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/orders' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant_id": "6253e03b",
    "merchant_number": "1001",
    "customer_id": 100,
    "customer_email": "alice@example.com",
    "total": "99.95",
    "total_shipping": "5.00",
    "payment_status": "not_paid",
    "date": "2018-01-25T01:25:27+01:00",
    "discount_codes": [
      {
        "code": "AUEX-8Q7L",
        "amount": "5.00"
      }
    ]
  }'

PUT /v2/orders/:merchant_id

Use this endpoint to update an existing order in LoyaltyLion, using your internal merchant_id to identify the order.

This is a full update and must include the order’s current payment, cancellation and refund status, including any relevant totals if required (total_paid and total_refunded).

The update endpoint is idempotent, so it is safe to call it every time an order is updated in your system.

Request

You must provide a JSON payload with the following fields:

FieldTypeRequiredDescription
payment_statusstringyesThe payment status of this order. Must be one of: not_paid , partially_paid and paid
cancellation_statusstringyesThe cancellation status of this order. Must be one of: not_cancelled and cancelled
refund_statusstringyesThe refund status of this order. Must be one of: not_refunded , partially_refunded and refunded
total_paidstringyesThe total amount that has been paid for this order. If the payment status is paid this must equal the order total
total_refundedstringyesThe total amount that has been refunded for this order

Response

Returns a 204 No Content response if the update was valid. If the order could not be updated, a 422 Unprocessable Entity response will be returned.

Example

curl -X PUT \
  --url 'https://api.loyaltylion.com/v2/orders/6253e03b' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_status": "partially_paid",
    "refund_status": "not_refunded",
    "cancellation_status": "not_cancelled",
    "total_paid": "50.00",
    "total_refunded": "0"
  }'

GET /v2/orders/:merchant_id

Return a single order, identified by your internal merchant_id.

Because orders in LoyaltyLion are copies of your own orders, this is not particularly useful for most applications but can help during development.

Request

This endpoint does not have any query parameters.

Response

This endpoint will return the order resource matching the provided merchant_id, or 404 Not Found if no order matched.

FieldTypeDescription
merchant_idstringUnique id of order in your store
totalstringOrder total, after shipping and tax, before discounts (e.g. ‘99.95’)
total_shippingstringTotal shipping (e.g. ‘2.50’)
total_paidstringTotal paid (e.g. ‘50.00’)
payment_statusstringOne of paid , partially_paid and not_paid
refund_statusstringOne of refunded , partially_refunded and not_refunded
cancellation_statusstringOne of cancelled , not_cancelled
paymentsarrayList of payment objects (see below)
refundsarrayList of refund objects (see below)
merchant_created_atstringAn ISO8601 timestamp representing when this order was created at your store
merchant_updated_atstringAn ISO8601 timestamp representing when this order was last updated at your store

Payment object

Payment objects represent individual transactions, if your platform provides individual transaction information for orders. They may have additional fields depending on the platform and transaction method.

FieldTypeDescription
gatewaystringThe payment gateway identifier, if supplied
created_atstringAn ISO8601 timestamp representing the time of this payment
amountstringThe payment amount, e.g. ‘20.00’

Refund object

Refund objects represent individual refund transactions, if your platform provides individual transaction information for order refunds. They may have additional fields depending on the platform and refund method.

FieldTypeDescription
created_atstringAn ISO8601 timestamp representing the time of this refund
amountstringThe refund amount, e.g. ‘15.00’

Example

curl \
  --url 'https://api.loyaltylion.com/v2/orders/6253e03b' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'