External Loyalty Program API (1.1.10)

Download OpenAPI specification:Download

API for an external loyalty program that is called by the enfore platform.

Subscription

Operations related to a loyalty program subscription.

Determine the status of a loyalty program subscription

Checks the status of a loyalty program subscription based on a subscription identifier.

Subscription identifiers are scanned or manually entered codes that identify a customer or member of a loyalty program.

The enfore runtime will use this endpoint to determine whether the scanned/entered identifier represents an active loyalty program subscription or not.

There are three possible success cases:

ACTIVE - The identifier represents an active subscription that points can be collected for.
INACTIVE - The identifier represents a subscription but that description is "inactive". That is, no points can be collected for it.
UNKNOWN - The identifier does not match any susbcription. This implies that no points can be collected.

Note that the external loyalty program must only return a failure if there is a technical problem. For identifiers that simply do not match any subscription, an UNKNOWN-success must be returned.

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

query Parameters

subscription_identifier required	string The identifier to check.
language	string <bcp47> Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag

Responses

200

The result of the verification.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

get /org/{org-id}/loyalty/subscriptions/verify

/org/{org-id}/loyalty/subscriptions/verify

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"subscription_status": "UNKNOWN",
"points_balance": 0,
"points_available_for_redemption": 0,
"contact": 
{"@type": "AnonymousContactInformation",
"name": "string",
"contact_address": 
{"full_address": "string",
"recipient_name": "string",
"care_of": "string",
"street_name": "string",
"street_number": "string",
"additional": "string",
"city": "string",
"zip": "string",
"country_code": "AF"
},
"contact_email": "user@example.com",
"contact_phone": "string",
"unique_instance_id": "string",
"external_data": "string",
"user_level_identifiers": 
[
{"identifier": "string",
"label": "string"
}
]
},
"@type": "SubscriptionVerificationSuccess"
}

Coupons

Operations related to loyalty program coupons. Includes operations to verify coupons, mark coupons as used and to restore used coupons.

Determine the status of a loyalty program coupon

Checks the status of a loyalty program coupon based on a coupon identifier.

Coupon identifiers are scanned or manually entered codes that identify a coupon/voucher of a specific loyalty program. Usually, such coupons/vouchers grant additional points based on their conditions. For example, "2x points on cat food".

The enfore runtime will use this endpoint to determine whether the scanned/entered identifier represents a coupon of the loyalty program and whether it is active or not.

There are three possible success cases:

ACTIVE - The identifier represents an active coupon that can be used (given that its constraints are matched).
REDEEMED - The identifier represents a coupon that has already been redeemed.
EXPIRED - The identifier represents a coupon that has already been expired.
UNKNOWN_IDENTIFIER - The identifier does not match any coupon.
REDEMPTION_STATUS_UNKNOWN - Determine the status of a loyalty program coupon.

Note that the external loyalty program must only return a failure if there is a technical problem. For identifiers that simply do not match any coupon, an UNKNOWN_IDENTIFIER-success must be returned.

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

query Parameters

coupon_code required	string The Coupon code to check.
subscription_identifier required	string The identifier to check.
language	string <bcp47> Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag

Responses

200

The result of the verification.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

get /org/{org-id}/loyalty/coupons/verify

/org/{org-id}/loyalty/coupons/verify

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"status": "UNKNOWN_IDENTIFIER",
"coupon_description": "string",
"identifier": "string",
"@type": "CouponVerificationSuccess"
}

Reports coupons as used.

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

subscription_identifier required	string [ 1 .. 256 ] characters Subscription identifier
selected_coupons required	Array of strings List of selected/used coupons
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag

Responses

200

The result of reporting the coupons.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

post /org/{org-id}/loyalty/coupons/mark-used/

/org/{org-id}/loyalty/coupons/mark-used/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"subscription_identifier": "string",
"selected_coupons": 
["string"
],
"language": "string"
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"@type": "CouponReportSuccess"
}

Restores coupons previously marked as used.

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

subscription_identifier required	string [ 1 .. 256 ] characters Subscription identifier
selected_coupons required	Array of strings List of selected/used coupons
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag

Responses

200

The result of restoring the coupons.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

post /org/{org-id}/loyalty/coupons/restore/

/org/{org-id}/loyalty/coupons/restore/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"subscription_identifier": "string",
"selected_coupons": 
["string"
],
"language": "string"
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"@type": "CouponReportSuccess"
}

Points

Operations related to loyalty program points. Include operations for calculating, granting and revoking points.

Calculate loyalty points for the specified basket

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

basket required	object (ExternalLoyaltyProgramBasket)
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag
subscription_identifier	string [ 1 .. 256 ] characters Identifier of subscription loyalty program
selected_coupons	Array of strings Optional list of Loyalty Program coupons that have been presented by the customer

Responses

200

The result of the calculation.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

post /org/{org-id}/loyalty/baskets/calculate/

/org/{org-id}/loyalty/baskets/calculate/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"basket": 
{"evaluation_date": "2025-04-23T13:33:19Z",
"total_gross_amount": 
{"value": 0,
"unit": "AUD"
},
"items": 
[
{"identifier": "string",
"product_id": "string",
"sales_unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_sales_units": 0,
"amount": 
{"value": 0,
"unit": "AUD"
},
"options": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"extra_charges": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"lot": "string",
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"sales_channel": "string"
},
"language": "string",
"subscription_identifier": "string",
"selected_coupons": 
["string"
]
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"calculated_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
],
"applied_coupons": 
["string"
],
"invoice_information": 
[
{"type": "string",
"text": 
["string"
]
}
],
"@type": "CalculationSuccess"
}

Calculate loyalty points for the specified refund basket

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

refund_basket required	object (LoyaltyProgramRefundBasket)
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag
subscription_identifier	string [ 1 .. 256 ] characters Identifier of subscription loyalty program
reference_of_grant	string [ 1 .. 256 ] characters Optional reference returned by the grant call of the now refunded items
refunded_invoice_id	string [ 1 .. 256 ] characters Technical identifier of the refunded invoice

Responses

200

The result of the calculation.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

post /org/{org-id}/loyalty/baskets/calculate-refund/

/org/{org-id}/loyalty/baskets/calculate-refund/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"refund_basket": 
{"date_of_sale": "2025-04-23T13:33:19Z",
"date_of_refund": "2025-04-23T13:33:19Z",
"total_gross_amount_of_refund": 
{"value": 0,
"unit": "AUD"
},
"total_gross_amount_of_sale": 
{"value": 0,
"unit": "AUD"
},
"items": 
[
{"item_identifier": "string",
"product_id": "string",
"sales_unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_refunded_sales_units": 0,
"refund_amount": 
{"value": 0,
"unit": "AUD"
},
"options": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"extra_charges": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"lot": "string",
"sales_category": "string",
"excluded_from_discounts": true,
"sales_information": 
{"number_of_sold_sales_units": 0,
"sales_item_amount": 
{"value": 0,
"unit": "AUD"
},
"granted_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
]
},
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"sales_channel": "string",
"granted_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
]
},
"language": "string",
"subscription_identifier": "string",
"reference_of_grant": "string",
"refunded_invoice_id": "string"
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"calculated_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
],
"applied_coupons": 
["string"
],
"invoice_information": 
[
{"type": "string",
"text": 
["string"
]
}
],
"@type": "CalculationSuccess"
}

Grants loyalty points

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

subscription_identifier required	string [ 1 .. 256 ] characters Identifier of subscription loyalty program
points_to_grant required	Array of objects (LoyaltyPoints) The points to be granted.
invoice_number required	string [ 1 .. 256 ] characters Invoice number
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag
basket required	object (ExternalLoyaltyProgramBasket)

Responses

200

The result of the granting.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

post /org/{org-id}/loyalty/baskets/grant-points/

/org/{org-id}/loyalty/baskets/grant-points/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"subscription_identifier": "string",
"points_to_grant": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
],
"invoice_number": "string",
"language": "string",
"basket": 
{"evaluation_date": "2025-04-23T13:33:19Z",
"total_gross_amount": 
{"value": 0,
"unit": "AUD"
},
"items": 
[
{"identifier": "string",
"product_id": "string",
"sales_unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_sales_units": 0,
"amount": 
{"value": 0,
"unit": "AUD"
},
"options": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"extra_charges": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"lot": "string",
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"sales_channel": "string"
}
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"reference": "string",
"@type": "PointsGrantingSuccess"
}

Revoke granted points

path Parameters

org-id

required

string

ID of the organization whose data is being accessed.

Request Body schema: application/json

refund_basket required	object (LoyaltyProgramRefundBasket)
subscription_identifier required	string [ 1 .. 256 ] characters Identifier of subscription loyalty program
points_to_revoke required	Array of objects (LoyaltyPoints) Number of points to be revoked
credit_memo_number required	string [ 1 .. 256 ] characters Invoice number
refunded_invoice_number required	string [ 1 .. 256 ] characters Refunded invoice number
language required	string <bcp47> [ 1 .. 256 ] characters Language tag that specifies the language in that localized results should be returned, if possible. See https://www.w3.org/TR/ltli/#dfn-language-tag
reference_of_grant	string [ 1 .. 256 ] characters Optional reference returned by the grant call of the now refunded items

Responses

200

The result of the revocation.

400

Invalid parameters were sent by the client

403

Credentials missing or not sufficient

404

Resource(s) not found or invalid identifier

422

Specified data is semantically incorrect.

post /org/{org-id}/loyalty/baskets/revoke-points/

/org/{org-id}/loyalty/baskets/revoke-points/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"refund_basket": 
{"date_of_sale": "2025-04-23T13:33:19Z",
"date_of_refund": "2025-04-23T13:33:19Z",
"total_gross_amount_of_refund": 
{"value": 0,
"unit": "AUD"
},
"total_gross_amount_of_sale": 
{"value": 0,
"unit": "AUD"
},
"items": 
[
{"item_identifier": "string",
"product_id": "string",
"sales_unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_refunded_sales_units": 0,
"refund_amount": 
{"value": 0,
"unit": "AUD"
},
"options": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"extra_charges": 
[
{"identifier": "string",
"product_id": "string",
"unit": 
{"value": 0,
"unit": "ENERGY_JOULES"
},
"number_of_units": 0,
"is_single_issue": true,
"amount": 
{"value": 0,
"unit": "AUD"
},
"sales_category": "string",
"excluded_from_discounts": true,
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"lot": "string",
"sales_category": "string",
"excluded_from_discounts": true,
"sales_information": 
{"number_of_sold_sales_units": 0,
"sales_item_amount": 
{"value": 0,
"unit": "AUD"
},
"granted_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
]
},
"taxes": 
["CH_STANDARD_VAT_2008"
]
}
],
"sales_channel": "string",
"granted_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
]
},
"subscription_identifier": "string",
"points_to_revoke": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
],
"credit_memo_number": "string",
"refunded_invoice_number": "string",
"language": "string",
"reference_of_grant": "string"
}

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all


{"revoked_points": 
[
{"points": 0,
"label": "string",
"reference": "string",
"item_identifier": "string"
}
],
"reference": "string",
"@type": "PointsRevokingSuccess"
}