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 optional query parameters with the request.

ParamDescription
since_idReturn only orders whose id is after the specified id
cursorA cursor to retrieve another page of results. Cursor pagination guidance
limitNumber of orders to return per request. Must be 1-500 (default: 100)
created_at_minReturn only orders created at or after this date (ISO 8601 format)
created_at_maxReturn only orders created at or before this date (ISO 8601 format)
updated_at_minReturn only orders last updated at or after this date (ISO 8601 format)
updated_at_maxReturn only orders last updated at or before this date (ISO 8601 format)

Response

This endpoint returns 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, tax, and discounts (for example, ‘99.95’)
total_taxstringTotal tax (for example, ‘0.50’)
total_shippingstringTotal shipping (for example, ‘2.50’)
total_discountsstringTotal discounts (for example, ‘5.00’)
total_paidstringTotal paid (for example, ‘50.00’)
total_refundedstringTotal refunded (for example, ‘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 ISO 8601 timestamp representing when this order was created in LoyaltyLion
updated_atstringAn ISO 8601 timestamp representing when this order was last updated in LoyaltyLion

Example

curl \
  --url 'https://api.loyaltylion.com/v2/orders?since_id=500' \
  --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, tax, and discounts (for example, ‘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 defaults 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.
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 ISO 8601 timestamp. Defaults 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, for example, “AU7X-8Q7L”
amountstringyesThe discount provided, for example, 5.00

Response

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

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/orders' \
  --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": "AU7X-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’s 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 paidthis 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 couldn’t be updated, a 422 Unprocessable Entity response is returned.

Example

curl -X PUT \
  --url 'https://api.loyaltylion.com/v2/orders/6253e03b' \
  --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 isn’t particularly useful for most applications but can help during development.

Request

This endpoint doesn’t have any query parameters.

Response

This endpoint returns the order resource matching the provided merchant_id, or 404 Not Found if no order matches.

FieldTypeDescription
merchant_idstringUnique id of order in your store
totalstringOrder total, after shipping, tax, and discounts (for example, ‘99.95’)
total_shippingstringTotal shipping (for example, ‘2.50’)
total_paidstringTotal paid (for example, ‘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 ISO 8601 timestamp representing when this order was created at your store
merchant_updated_atstringAn ISO 8601 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 ISO 8601 timestamp representing the time of this payment
amountstringThe payment amount, for example, ‘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 ISO 8601 timestamp representing the time of this refund
amountstringThe refund amount, for example, ‘15.00’

Example

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