Download OpenAPI specification:Download
The Currency Alliance API facilitates various use cases for Loyalty Commerce. Our API allows our Partners to:
The Currency Alliance API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Calls to the API have to be properly authenticated using your public and secret API keys. The keys are available in the 'CREDENTIALS' section of the "Loyalty API" module in the Management Dashboard. These keys MUST never be exposed to the public or any unauthorized person.
The API is designed for a server to server communication. If you want to communicate with the API from a client it must be through a server environment, to protect the integrity of the requests and the API keys, and not expose them on front-end platforms.
The API authenticates every request based on two elements - Credential and Signature. Every request must include an Authorization header with the following two elements.
Credential=<public-key>, Signature=<calculated-signature>
In this parameter, the API requires you to provide the <public-key> that is unique to your account. Your keys are available in the 'CREDENTIALS' section of the "Loyalty API" module in the Management Dashboard.
The signature is a HMAC-SHA256 hash in hexadecimal of the request content, using the private_key as the key.
Keep in mind that the string you use to generate the signature and the string you send to the API has to be exactly the same. This includes newlines and spaces. If you compress the JSON body of your request, after generating the signature, the request will be rejected.
These types of requests use the string representation of the body to calculate the signature.
For example, for the request with body: {"foo": "bar"} the signature calculated using sec_12345 as the private key would be 4d84ba663b9c6179dd98023087da5baa8a4e3eb59ba45284935261350ba70742
This type of request uses the query string to calculate the signature. Take into account that the "?" character must not be included while calculating the signature.
For example, for the request with query string: ?foo=bar the signature calculated using sec_12345 as the private key would be 88d64dfcb542c35dc22bae059bd5f5a5d038572a7b391dfc4cd5f3a5530c1760 which is the hash for the string "foo=bar"
To generate the signature of a GET request without any parameters, simply encode an empty string.
The API uses asymmetric cryptography to authenticate requests using the API keys we provide. This provides the following assurances:
The API only supports requests over HTTPS.
The API supports idempotent requests to safely retry requests without having to worry about doing the same operation more than once. For example, if there's a connection error generating a gift card, you can retry the request with the same idempotency key without having to worry about creating multiple gift cards.
To send an idempotent request, include an additional Idempotency-Key: <key> header in the request. An Idempotency Key <key> is a unique identifier generated by the client with a length between 1 and 255 characters. While this can be any type of unique key, we recommend a UUID to avoid collisions. An Idempotency key expires 8 hours after the initial request.
In a repeated request the response will always have the response body of the original request, along with the same status and 400 errors, if any. The response will also include the header Idempotency-Repeated: true. In the rare instances where a request is repeated while the first one has not been completed yet, the API will respond with a 409 - Conflict status.
The API supports idempotency on POST and PATCH requests. Since GET, PUT and DELETE are idempotent by default, the Idempotency-Key header will be ignored.
Currency Alliance acts as a connectivity bridge between various partners using its standardized APIs and interface, hence, shielding each partner from the complexity, nuances, and customizations of hundreds of loyalty systems and merchant partners. However, the interacting partners need to have a common reference for a transaction in their own system for easy reconciliation as well as for customer support purposes. In this section, you will find information on some key fields and attributes that are used through our API and on different objects. This information will help you understand how to use these key fields.
The field external_reference is used for each transaction request to provide a unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field.
The field loyalty_system_id is returned by our system on each transaction and it provides the unique identifier in the partner loyalty system. This ID is not generated by Currency Alliance but is provided by the partner loyalty program and hence could be used as a common field for reconciliation between your system and the partner's system.
Sometimes, a loyalty program requires you to send some additional data to connect. For example, user_id, application_id, partner_code, etc. You will be able to provide the data in this field for all the transactions with the partner loyalty program. To check if and what additional data is required by the partner loyalty program, refer to the Partners Endpoint.
Our API can be used for numerous Loyalty Commerce use cases. Some of the most common use cases are mentioned below along with the information on which Endpoints to use for each use case. There are auxiliary Endpoints that could be used to enhance your integration and customer experience. For example, you could pull all transaction history out via the API into your Business Intelligence or data staging environments or you could validate the member details before issuing Loyalty Currency Units.
The underlying objective of this use case is to “give Loyalty Currency Units to a member” for one reason or another. The reason could be a purchase of a product, their birthday, completion of a survey, referral, customer service issue, etc. Furthermore, you may want to give the member units of your own Loyalty Currency or one of your Partners’ Loyalty Currency.
You should use Accruals Endpoints for this use case. There are three Endpoints that can be used for issuing your or a Partner’s currency. You can use any one of the Endpoints or a combination of them to issue Loyalty Currency Units to the member.
This Endpoint is to be used when you know the exact number of Loyalty Currency Units to give to a member. In this scenario, you are calculating the number of Loyalty Currency Units in your environment and providing the exact number of units in the endpoint.
This Endpoint is to be used when you would like to give the number of Loyalty Currency Units based on Purchase Rule(s) defined in the Currency Alliance system. For example, giving points worth 1% of the fiat transaction amount. In this case, your application does not need to know how to calculate the number of Loyalty Currency Units or even the cost of the Loyalty Currency Units in any of your Partners' programs.
This Endpoint is to be used when you would like to issue the number of Loyalty Currency Units based on pre-defined Activity Rule(s) in the system. For example, you might offer 200 points for posting a product review or referring a friend.
Our API provides tools for quick collaboration among brands to enable their respective members to exchange loyalty units between programs. The exchange could be one-way only, or both directions – in and out – of the programs. Use the Loyalty Currency Exchange Endpoints to implement this use case. There are 2 Endpoints that can be used to enable exchange between partners.
This Endpoint allows you to simulate how many Loyalty Currency units the member would receive of a Partner’s Loyalty Currency in exchange. This can be used to show the member how many points in one or more programs they could get if completing the exchange.
This Endpoint allows you to comlete the exchange Loyalty Currency units to the Partner’s Loyalty Currency.
Tip: You could use the Partners Endpoints to get the list of Exchange Partners and automatically display the fields required for each program to complete the exchange. This will be necessary for loyalty programs that require more member validation fields than just the membership number.
Our Redemption Endpoints have standardized the redemption process across various types of loyalty programs and underlying loyalty systems. This shields you from needing to understand the underlying complexity to integrate into a new loyalty system or modifying the existing integration for a different set of parameters for a new partner.
You should use Standard Redemption Endpoints for this use case. There are four Endpoints that can be used for allowing a Partner’s Loyalty Currency as a form of payment. You can use any one of the Endpoints or a combination of them depending on your customer journey. Although not necessary, we highly recommend you use the “Lookup a Member” Endpoint to validate if the member exists and if they have enough balance to complete the payment before submitting the payment transaction.
Strictly speaking, Loyalty Exchange and Exchange for Gift Cards are also redemptions, but we provide explicit Endpoints for those actions due to the very high occurrence of those use cases in the industry. Standard Redemptions refers to any other redemptions where the Partners have allowed the member to redeem (exchange) their Loyalty Currency Units for your Products and Services. The products and services may range from flower delivery to booking a trip, buying an insurance plan, topping up their mobile plan, paying at a restaurant, buying concert tickets, or even applying points toward the purchase of a car.
To simulate the redemption action and provide information to the member such as the number of points required to complete the action, cancellation allowed, etc. without actually deducting the points from their balance or completing the transaction.
Deduct points from the member’s account in exchange for the product or service offered.
If allowed by the Partner, you may use this Endpoint to notify of any modification in an already completed Redemption. The system will automatically identify if more points are to be redeemed or points are to be refunded to the member.
If allowed by the Partner, you may use this Endpoint to cancel an already completed Redemption to refund the points.
Member Endpoints can be used to create a new member, look up information on a member, retrieve a member's details to your system, or update any member's details. Only the Currency Owner i.e. the loyalty program to which the member belongs has access to create a member or update a member.
The Partners could look up a member to confirm if the member exists, check the member account balance, or other details of the member record based on permissions granted by the Currency Owner.
Currency Alliance has standardized these Endpoints and orchestrates the calls to various Loyalty programs to validate a member, get member details, etc. if the Currency Alliance platform is not the primary data store for the relevant loyalty program.
The Member Object represents a member record. For the loyalty programs where Currency Alliance is not the primary data store for their members, the system will connect with the loyalty program system to fetch the member information and present it in the following format.
| additional_information | object |
| address_line1 | string Address line 1 (e.g. building, apartment, suite, unit, street) |
| address_line2 | string Address line 2 (e.g. community, neighborhood) |
| address_line3 | string Address line 3 (other information) |
| balance | integer Member’s balance in number of Loyalty Currency Units. The field will be null if the Currency Owner has not granted access to member’s balance. |
Array of objects | |
| birth_date | string <YYYY-MM-DD> Member’s date of birth |
| city | string City, district, suburb, town, or village. |
| country | string ISO 3166-1 alpha-3 of the country |
string Member’s email address | |
| first_name | string Member’s First Name |
| gender | string Enum: "male" "female" "other" |
| id | string Unique internal Currency Alliance identifier generated by the system for each member. |
| last_name | string Member's Last Name |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| loyalty_program_identifiers | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| loyalty_system_balance | string <decimal> |
| phone_number | string Member's contact number. |
| postal_code | string ZIP or postal code. |
| state | string State, county, province, or region. |
object | |
| type | string The member type. |
{- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}This Endpoint is only accessible by Currency Owners to create a member record if Currency Alliance is the main points bank i.e. the single source of truth for the loyalty program.
Each member object is associated with one loyalty currency. Thus, the same person associated with two different loyalty programs would have two member objects, each with a different corresponding loyalty_program_identifiers and loyalty_currency.
An important attribute is returned in all successful responses - loyalty_program_identifiers, which is a unique internal identifier for a member object across the entire Currency Alliance platform.
| loyalty_program_identifiers required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| address_line1 | string Address line 1 (e.g. building, apartment, suite, unit, street) |
| address_line2 | string Address line 2 (e.g. community, neighborhood) |
| address_line3 | string Address line 3 (other information) |
Array of objects | |
| birth_date | string <YYYY-MM-DD> Member’s date of birth |
| city | string City, district, suburb, town, or village. |
| country | string ISO 3166-1 alpha-3 of the country |
string Member’s email address | |
| first_name | string Member’s First Name |
| gender | string Enum: "male" "female" "other" |
| last_name | string Member’s Last Name |
| phone_number | string Phone number of the member in E.164 format |
| postal_code | string ZIP or Postal Code |
| state | string State, county, province, or region. |
| tier | string |
| type | string The member type. |
{- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "last_name": "Drennen",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "phone_number": "+443031237300",
- "postal_code": 1609,
- "state": "New York",
- "tier": "gold",
- "type": "individual"
}{- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}This Endpoint allows you to update the information of an existing member. This Endpoint is only accessible by Currency Owners to update a member record in Currency Alliance.
| loyalty_program_identifiers required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| address_line1 | string Address line 1 (e.g. building, apartment, suite, unit, street) |
| address_line2 | string Address line 2 (e.g. community, neighborhood) |
| address_line3 | string Address line 3 (other information) |
Array of objects | |
| birth_date | string <YYYY-MM-DD> Member’s date of birth |
| city | string City, district, suburb, town, or village. |
| country | string ISO 3166-1 alpha-3 of the country |
string Member’s email address | |
| first_name | string Member’s First Name |
| gender | string Enum: "male" "female" "other" |
| last_name | string Member’s Last Name |
| phone_number | string Phone number of the member in E.164 format |
| postal_code | string ZIP or Postal Code |
| state | string State, county, province, or region. |
| tier | string |
| type | string The member type. |
{- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "last_name": "Drennen",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "phone_number": "+443031237300",
- "postal_code": 1609,
- "state": "New York",
- "tier": "gold",
- "type": "individual"
}{- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}This Endpoint allows you to validate a member and get member details including balance and tier if provided access by the Currency Owner. Where Currency Alliance is not the Main Points Bank, the system will call the Loyalty Program to validate if the member exists, conditional upon if this option is available from the Currency Owner.
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| loyalty_program_identifiers required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| linked_loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Deprecated Replaced by loyalty_system_data |
{- "linked_loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "metadata": { }
}{- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}All actions in the system that result in the movement of any Loyalty Currency are represented by a unique Transaction object. E.g. some of the actions are:
Transaction Endpoints can be used to create a transaction, retrieve information of a transaction, all transactions of a member, or all transactions related to your account. These Endpoints can also be used to cancel or update a transaction.
NOTE: Create a Transaction CANNOT be used to do accruals and redemptions, including Gift Cards and Currency Exchange. Use Accruals and Redemptions Endpoints for such actions; the system will automatically create the underlying required transaction.
| amount | integer The transaction amount in the Loyalty Currency Units |
| bonus | boolean Indicates whether the transaction is a bonus one. |
| completed_at | string <date> The date and time when this transaction was completed based on the status and release date. |
| created_at | string <date> The date and time when this transaction was created. Note that it could be different from when the transaction is completed based on the status and release date. |
object Represents an account in the system. | |
| external_reference | string A unique identifier that can be used as a reference to uniquely identify the action in your system. |
| id | string Unique internal identifier generated by the system for each Transaction. |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners information.. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| loyalty_system_id | string Unique transaction identifier provided by the loyalty system. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
object Represents an account in the system. | |
| reason | string The textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created. |
| reason_code | string Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions. |
Activity Rule (object) or Gift Card Code (object) or Purchase Rule (object) or Standard redemption (object) or Standard redemption adjustment (object) or Standard redemption cancellation (object) This provides data about the related action that created the transaction. Actions could be the execution of transaction rule(s), activity rule(s), or a redemption. It is different from Metadata field because Metadata is additional optional information whereas this field is mandatory for certain actions such as Purchase rule, Activity rule, and Redemptions. | |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. |
| status | string Enum: "adjusted" "cancelled" "completed" "pending" "pending_external_approval" "rejected" "reversed" Provides the current status of the transaction. Transactions executed completely have the status set to |
| status_message | string The detailed reason why the transaction is not in the |
| status_message_code | string Enum: "release_date_not_reached" "pending_external_approval" "member_does_not_exist" The code representing the details about the transaction status when the transaction status is not |
| sub-type | string Enum: "activity_rule" "adjustment_decrease" "adjustment_increase" "buy" "cancellation" "in" "member" "member_to_member" "other" "out" "partner" "partner_to_partner" "purchase_rule" "self_transfer" "standard" This field provides further granular information about certain types of transactions. |
| type | string Enum: "accrual" "gift_card_exchange" "loyalty_currency_expiration" "loyalty_currency_generation" "loyalty_currency_purchase" "loyalty_currency_withdrawal" "member_exchange" "redemption" "transfer" "reversal" "wholesale_exchange" A transaction will always have a type associated with it. |
{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}This Endpoint allows you to retrieve the details of all the transactions of the specified member. To retrieve information about a specific transaction, use 'Retrieve a transaction' Endpoint.
| created_at__range | string <YYYY-MM-DD[Thh:mm[:ss][Z]],YYYY-MM-DD[Thh:mm[:ss][Z]]> Example: created_at__range=2020-05-02,2020-06-04T09:35:25Z Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| status | string Enum: "adjusted" "cancelled" "completed" "pending" "pending_external_approval" "rejected" "reversed" Provide value to filter transactions by status. Multiple values are accepted, separated by commas. |
| type | string Enum: "accrual" "gift_card_exchange" "loyalty_currency_expiration" "loyalty_currency_generation" "loyalty_currency_purchase" "loyalty_currency_withdrawal" "member_exchange" "redemption" "reversal" "transfer" "wholesale_exchange" Provide value to filter transactions by type. Multiple values are accepted, separated by commas. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
{- "member": {
- "id": "M12334532"
}, - "loyalty_currency": "EXAMPLE_POINTS"
}{- "count": 10,
- "previous": "string",
- "results": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}This Endpoint allows you to retrieve the details of all the transactions. To retrieve information about a specific transaction, use 'Retrieve a transaction' Endpoint.
| created_at__range | string <YYYY-MM-DD[Thh:mm[:ss][Z]],YYYY-MM-DD[Thh:mm[:ss][Z]]> Example: created_at__range=2020-05-02,2020-06-04T09:35:25Z Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| status | string Enum: "adjusted" "cancelled" "completed" "pending" "pending_external_approval" "rejected" "reversed" Provide value to filter transactions by status. Multiple values are accepted, separated by commas. |
| type | string Enum: "accrual" "gift_card_exchange" "loyalty_currency_expiration" "loyalty_currency_generation" "loyalty_currency_purchase" "loyalty_currency_withdrawal" "member_exchange" "redemption" "reversal" "transfer" "wholesale_exchange" Provide value to filter transactions by type. Multiple values are accepted, separated by commas. |
{- "count": 10,
- "previous": "string",
- "results": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}This Endpoint allows you to create a transaction in the system. This Endpoint should ONLY be used for transaction types of "transfer" such as from a member to another member, from one partner account to another partner account, or transfer between your own accounts. This Endpoint should NOT be used for issuing Currency to members, exchanging loyalty currencies, redeeming Gift Cards, or other redemptions. Relevant Endpoints (Accruals and Redemptions) should be used for the corresponding use cases.
| amount required | integer The transaction amount in units of the Loyalty Currency |
required | MemberIdentifiersField (object) or Account id (string) or Partner id (string) The destination for the transaction i.e. who is receiving the loyalty currency units. Depending on the type of transaction, it could either be a member or a partner account. In case of transferring units to a partner account, provide the Account ID as a string input. You could also send the Partner ID in this field. In the latter case, the system will automatically select the default account associated with the Partner ID. In case of transferring units from a member – you should send the loyalty_program_identifiers (such as membership id, last name, etc) as an object. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
required | MemberIdentifiersField (object) or Account id (string) or Partner id (string) The origin for the transaction i.e. who is issuing or providing the loyalty currency units. Depending on the type of transaction, it could either be a member or a partner account. In case of transferring units from a partner account, provide the Account ID as a string input. You could also send the Partner ID in this field. In the latter case, the system will automatically select the default account associated with the Partner ID. In case of transferring units from a member – you should send the loyalty_program_identifiers (such as membership id, last name, etc) as an object. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| reason | string Textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created. |
| reason_code | string Enum: "bonus_reward" "customer_service_issue" "gift" "lottery_reward" "other" "participation_check_in_reward" "product_purchase" "referral_reward" "service_purchase" "sharing_information_reward" "social_action_reward" "special_event_reward" Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions. |
{- "amount": 100,
- "destination": {
- "id": "M12334532"
}, - "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "metadata": {
- "foo": "bar"
}, - "reason": "Christmas bonus",
- "origin": {
- "id": "M12334532"
}, - "reason_code": "product_purchase"
}{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}This Endpoint allows you to retrieve the details of a specific transaction.
| id required | string Unique internal identifier generated by the system for each transaction. |
{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}This Endpoint allows you to update the details of a specific transaction. A transaction can only be updated if its status is pending and the update is requested either by the owner of the origin account of the transaction or the creator of the transaction.
NOTE: Use the "Adjust a Redemption" Endpoint to refund or modify a Redemption transaction, if permitted by the Currency Owner.
| id required | string Unique internal identifier generated by the system for each transaction. |
| amount | integer Amount of loyalty currency units to give. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| reason | string Textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created. |
| reason_code | string Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted but will be truncated to the minute. Refer Transaction Object for further details. |
{- "amount": 100,
- "loyalty_system_data": { },
- "metadata": {
- "foo": "bar"
}, - "reason_code": "string",
- "reason": "Christmas bonus",
- "release_date": "2020-10-10T12:12"
}{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}This Endpoint allows you to cancel a specific transaction. A transaction can only be canceled if its status is pending and the cancellation is requested either by the owner of the origin account of the transaction or the creator of the transaction.
NOTE: Use the "Adjust a Redemption" Endpoint to refund or modify a Redemption transaction, if permitted by the Currency Owner.
| id required | string Unique internal identifier generated by the system for each transaction. |
{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}Direct Accruals Endpoint is to be used in the scenarios where you know in advance the exact number of loyalty currency units that are to be issued to a member and from which account if multiple accounts are available.
This Endpoint allows you to create a standard direct accrual in the member’s account. This Endpoint will automatically create a transaction with type “Accrual” in the system.
| amount required | integer The transaction amount in units of the Loyalty Currency |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
required | Account id (string) or Partner id (string) The origin for the accrual i.e. who is issuing or providing the loyalty currency units. You can either send the Account ID or you can send the Partner ID in this field. In the latter case, the system will automatically select the default account associated with the Partner ID. |
| bonus | boolean Default: false Indicates whether the transaction is in bonus points. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| reason | string Textual description for why the transaction was created. This text is presented to the origin and destination account holders in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this transaction was created. |
| reason_code | string Enum: "bonus_reward" "customer_service_issue" "gift" "lottery_reward" "other" "participation_check_in_reward" "product_purchase" "referral_reward" "service_purchase" "sharing_information_reward" "social_action_reward" "special_event_reward" Reason code for why the transaction was created. This field is used for reporting purposes if the ‘reason’ field is dynamic and can vary within one category of transactions. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted but will be truncated to the minute. |
{- "amount": 1000,
- "bonus": false,
- "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "origin": "acc_abcd1234",
- "reason": "Christmas bonus",
- "reason_code": "product_purchase",
- "release_date": "2020-10-10T12:12"
}{- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}The Purchase Endpoints allows you to simulate or execute a purchase rule to issue loyalty currency units to your members. The purchase loyalty rules can be defined in the following section in the Management Dashboard:
Loyalty Rules > Purchase Rules
Simulates the rules to identify the number of Loyalty Currency Units to be given to the members based on the purchase of a product. This Endpoint is used in scenarios where one might want to show the user how many units of the Loyalty Currency will be given for a corresponding action. For example, if user buys a particular item then how many Currency units will be issued. This does not result in issuance of Currency units or execution of a transaction in the system, it is only a simulation.
| fiat_amount required | string <decimal> Amount of the purchase in decimal format. |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| tags | Array of strings List of tags. Only the rules that either have no tags or at least one of these tags will be executed. |
{- "fiat_amount": "20.00",
- "fiat_currency": "USD",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "tags": [
- "promo20"
]
}{- "total": 0,
- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "is_bonus": false,
- "name": "Purchase Rule #1"
}
}
]
}Trigger the loyalty rules matching the purchase from the specified member.
| fiat_amount required | string <decimal> Amount of the purchase in decimal format. |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| preferred_execution_mode | string Enum: "single_transaction" "multiple_transactions" This field identifies if there are multiple loyalty rules to be executed based on the purchase details, the system should combine all the rules and create only one transaction or execute each rule separately to create a corresponding transaction. The default mode, and recommended, is `multiple_transactions. However, note that some partner loyalty systems may not allow multiple transactions. For such loyalty partners, the Currency Alliance platform will automatically override this field to create "single_transaction". |
| reason | string This field can be used when the preferred_execution_mode is single_transaction. You can provide a combined reason for all the purchase rules that are executed as a single transaction. If no value is provided, the Currency Alliance system will concatenate the reason for each purchase rule. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will be truncated to the minute. |
| tags | Array of strings List of tags. Only the rules that either have no tags or at least one of these tags will be executed. |
{- "external_reference": "string",
- "fiat_amount": "20.00",
- "fiat_currency": "USD",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "preferred_execution_mode": "single_transaction",
- "reason": "string",
- "release_date": "2020-10-10T12:12",
- "tags": [
- "promo20"
]
}{- "id": "pre_abcd1234",
- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "is_bonus": false,
- "name": "Purchase Rule #1"
}, - "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}
], - "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}This Endpoint allows you to retrieve information about a specific purchase rule execution.
| id required | string Unique internal identifier that was generated by the system for the purchase rule execution. |
{- "id": "pre_abcd1234",
- "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}This Endpoint allows you to retrigger purchase rule(s) if the purchase order in your system has been updated. This is only available if the original transaction is in pending status.
An example where this Endpoint is used is when points are issued to a member for a hotel booking but it is pending for a future date. Before the future date is reached, if the member changes the underlying hotel booking, this endpoint would retrigger the purchase rules based on the new booking information.
| id required | string Unique internal identifier that was generated by the system for the purchase rule execution. |
| fiat_amount required | string <decimal> Amount of the purchase in decimal format. |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| reason | string This field can be used when the preferred_execution_mode is single_transaction. You can provide a combined reason for all the purchase rules that are executed as a single transaction. If no value is provided, the Currency Alliance system will concatenate the reason for each purchase rule. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will be truncated to the minute. |
| tags | Array of strings List of tags. Only the rules that either have no tags or at least one of these tags will be executed. |
{- "fiat_amount": "20.00",
- "fiat_currency": "USD",
- "loyalty_system_data": { },
- "metadata": {
- "foo": "bar"
}, - "release_date": "2020-10-10T12:12",
- "reason": "string",
- "tags": [
- "promo20"
]
}{- "id": "pre_abcd1234",
- "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}This Endpoint allows you to cancel the transaction(s) made previously during the execution of purchase rule(s). This is only available if the original transaction is in pending status.
An example where this Endpoint is used is when points are issued to a member for a hotel booking but it is pending for a future date. Before the future date is reached, if the member cancels the underlying hotel booking, this endpoint would cancel the pending transaction(s).
| id required | string Unique internal identifier that was generated by the system for the purchase rule execution. |
{- "id": "pre_abcd1234",
- "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}The Activities Endpoints allows you to simulate or execute an activity rule to issue loyalty currency units to your members. The activity loyalty rules can be defined in the following section in the Management Dashboard:
Loyalty Rules > Activity Rules
Simulates an execution of an activity rule for the specified Loyalty Currency. This Endpoint is used in scenarios where one might want to show the user how many units of the Loyalty Currency will be given based on certain activity. For example, if user buys a particular item and shares it on social media then how many Currency units will be provided for that activity. This does not result in issuance of Currency units or execution of a transaction in the system, it is only a simulation.
| activity_ids required | Array of strings Unique identifiers defined for each activity for the Loyalty Currency. Refer to the Activity rule in the Management Dashboard Section Loyalty Rules > Activity Rules for this field. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
{- "activity_ids": [
- "birthday"
], - "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}
}{- "total": 0,
- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "name": "Activity Rule #1"
}
}
]
}Trigger activity rules for the specified Loyalty Currency.
| activity_ids required | Array of strings Unique identifiers defined for each activity for the Loyalty Currency. Refer to the Activity rule in the Management Dashboard Section Loyalty Rules > Activity Rules for this field. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will truncated to the minute. |
{- "activity_ids": [
- "birthday"
], - "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "release_date": "2020-10-10T12:12"
}{- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "name": "Activity Rule #1"
}, - "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}
], - "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}Redemptions are referred to as any action that allows the members to redeem the value of their Loyalty Currency Units in exchange for any product, services, or any other redemption options. Standard Redemption Endpoints provides a standardized way for you to allow members to redeem their Loyalty Currency Units for any type of product or service that is not a Gift Card or an Exchange into another loyalty program’s Loyalty Currency.
Standard Redemptions are any redemptions where the Partners have allowed the member to redeem (exchange) their Loyalty Currency Units for your Products and Services. The products and services may range from flower delivery to booking a trip, buying an insurance plan, topping up their mobile plan, paying at a restaurant, buying concert tickets, or even applying points toward the purchase of a car.
The Partners define in the Partnership Settings that the members can redeem their points in various product and service categories. Thus, it is very important that you provide information about the product and services in the request message. If you don’t have defined product categories and details, simply send “General” in the 'category' field.
Some Partners may allow an option to cancel or modify the redemption. This information is provided in the response messages of the Endpoints for you to inform the member before completing the redemption.
This Endpoint is used in scenarios where one might want to simulate the redemption of Loyalty Currency Units for a product or a service without actually completing the transaction. This can be used to show a member how much it would cost in points for the products or services. For example, if a member would like to redeem points for a hotel booking, cab ride, shoe purchase, spa treatment, or any other product/service, this Endpoint would be used to calculate how many Loyalty Currency Units would be required as a form of payment for the product/service.
You can send a list of products and services along with the amount or the price to identify the Loyalty Currency Units required to be redeemed for each type of product or service. The amount, or the price, can be provided either in units in the field "loyalty_amount" or in fiat currency in the field "fiat_amount". It is highly advisable to send the information as well as the member information as the redemption value per Loyalty Currency Unit may depend on any of these factors. For example, a Gold member may require a fewer number of Loyalty Currency Units than a Bronze member to redeem in exchange for a hotel booking whereas booking a cab ride may not depend on the member tier.
The response will contain the total amount in fiat currency and total number of Loyalty Currency Units required for this redemption. If the member information is sent then the response will also provide additional information such as their available balance in Loyalty Currency Units and fiat value of those Loyalty Currency Units for General product if the member does not have sufficient balance to complete this redemption. Additional information in the response would be whether the Currency Owner allows adjustments and cancellations of Redemptions or not.
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
required | Array of Fiat Amount (object) or Loyalty amount (object)[ items <= 50 items ] An list of products and services representing itemized invoice based on product categories. Each item contains the amount or the price of the product or service to identify the Loyalty Currency Units required to be redeemed in exchange. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| metadata | object Deprecated Replaced by loyalty_system_data |
{- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": { },
- "redemption_items": [
- {
- "category": "general",
- "channel": "Mobile App",
- "country": "USA",
- "fiat_amount": "340.35",
- "fiat_currency": "USD",
- "metadata": {
- "foo": "bar"
}, - "product_code": "string",
- "product_description": "string",
- "promotion_code": "promo123",
- "sub_category": "concert_tickets"
}
]
}{- "adjustment_allowed": true,
- "loyalty_currency": "EXAMPLE_POINTS",
- "maximum_fiat_balance": "700.00",
- "member": {
- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}, - "metadata": {
- "foo": "bar"
}, - "redemption_items": [
- {
- "category": "general",
- "channel": "Mobile App",
- "country": "USA",
- "fiat_amount": "340.35",
- "fiat_currency": "USD",
- "loyalty_amount": 45564,
- "metadata": {
- "foo": "bar"
}, - "sub_category": "concert_tickets"
}
], - "sufficient_balance": true,
- "total_fiat_amount": "340.35",
- "total_loyalty_amount": 45564
}This Endpoint is used to complete the exchange of Loyalty Currency Units for a product or a service. This Endpoint will automatically create a transaction with type "Redemption" in the system.
It is mandatory to provide the information regarding the product or the service as the redemption value per Loyalty Currency Unit may depend on any of these factors. For example, a Gold member may require fewer number of Loyalty Currency Units than a Bronze member to redeem in exchange for a product. If you are not sure of the product category, then send "General" as the default option.The amount can be provided either in units in the field "loyalty_amount" or in fiat currency in the field "fiat_amount".
The response will contain the total amount in fiat currency and total number of Loyalty Currency Units required for this redemption. The response will also provide additional information such as whether the Currency Owner allows adjustments and cancellations of Redemptions or not.
| external_reference required | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| reason required | string The textual description for why the redemption was done. This text may be presented to the member in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this redemption was done. Please note that some partners may provide a specific format for this field. |
required | Array of Fiat Amount (object) or Loyalty amount (object)[ items <= 50 items ] An list of products and services representing itemized invoice based on product categories. Each item contains the amount or the price of the product or service to identify the Loyalty Currency Units required to be redeemed in exchange. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object JSON object. Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as information about the store, information about the member, entity redeeming the currency, partner codes, connectivity information, or anything else that could be helpful for connections, analytics, or reporting. |
{- "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "reason": "string",
- "redemption_items": [
- {
- "category": "general",
- "channel": "Mobile App",
- "country": "USA",
- "fiat_amount": "340.35",
- "fiat_currency": "USD",
- "metadata": {
- "foo": "bar"
}, - "product_code": "string",
- "product_description": "string",
- "promotion_code": "promo123",
- "sub_category": "concert_tickets"
}
]
}{- "url": "string"
}Some Currency Owners may allow for adjustments or even a full refund on an existing Redemption. This Endpoint is used to adjust or modify an already made redemption. For example, if there is a change in redemption product or invoice where the customer has added or removed some products or the quantity, thus, resulting in a different fiat_amount, this Endpoint will be used to reflect the new state of the redemption and refund/redeem points accordingly.
The input request structure remains the same as "Execute a Redemption". You should send all the information regarding the products or the services as per the new updated redemption including the products and services that have not been changed. The system will automatically identify the changes and make adjustments accordingly.
This Endpoint will update the status of the original Redemption transaction as "Adjusted" and will create a new transaction of type "Redemption" and sub-type "Adjustment".
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| new_external_reference required | string Unique identifier to be used as reference during reconciliation process. This could be the invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the redemption. Depending on your internal system, you may have a new identifier or it may be the same identifier as the old redemption. In latter case, send the same value in this field as for the previous_external_reference. |
| previous_external_reference required | string Unique identifier to be used as reference during reconciliation process. IMPORTANT: Send the external reference id of the latest adjustment if there were any adjustments made prior to this request. |
| previous_transaction_id required | string Unique identifier generated in the Currency Alliance system for each transaction. Send the transaction id that was created for the previous redemption transaction. IMPORTANT: Send the transaction id of the latest adjustment if there were any adjustments made prior to this request. |
| reason required | string The textual description for why the redemption was done. This text may be presented to the member in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this redemption was done. Please note that some partners may provide a specific format for this field. |
required | Array of Fiat Amount (object) or Loyalty amount (object)[ items <= 50 items ] An list of products and services representing itemized invoice based on product categories. Each item contains the amount or the price of the product or service to identify the Loyalty Currency Units required to be redeemed in exchange. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object JSON object. Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as information about the store, information about the member, entity redeeming the currency, partner codes, connectivity information, or anything else that could be helpful for connections, analytics, or reporting. |
{- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "new_external_reference": "abcd1234",
- "previous_external_reference": "abcd1234",
- "previous_transaction_id": "tx_abc12312345",
- "reason": "string",
- "redemption_items": [
- {
- "category": "general",
- "channel": "Mobile App",
- "country": "USA",
- "fiat_amount": "340.35",
- "fiat_currency": "USD",
- "metadata": {
- "foo": "bar"
}, - "product_code": "string",
- "product_description": "string",
- "promotion_code": "promo123",
- "sub_category": "concert_tickets"
}
]
}{- "external_reference": "abcd1234",
- "fiat_amount_difference": "12.34",
- "loyalty_amount_difference": 123,
- "member": {
- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}, - "metadata": {
- "foo": "bar"
}, - "previous_external_reference": "abcd1234",
- "previous_transaction_id": "tx_abc12312345",
- "reason": "string",
- "total_fiat_amount": "340.35",
- "total_loyalty_amount": 45564,
- "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}, - "redemption_items": [
- {
- "category": "general",
- "channel": "Mobile App",
- "country": "USA",
- "fiat_amount": "340.35",
- "fiat_currency": "USD",
- "loyalty_amount": 45564,
- "metadata": {
- "foo": "bar"
}, - "sub_category": "concert_tickets"
}
]
}This Endpoint allows you to cancel a specific Redemption. A Redemption can only be canceled if the Currency Owner allows such an action. Simulate a Redemption provides the information whether the cancellation is allowed or not.
This Endpoint will update the status of the original Redemption transaction as "Cancelled" and will create a new transaction of type "Redemption" and sub-type "Cancellation".
| previous_external_reference required | string Unique identifier to be used as reference during reconciliation process. IMPORTANT: Send the external reference id of the latest adjustment if there were any adjustments made prior to this request. |
| previous_transaction_id required | string Unique identifier generated in the Currency Alliance system for each transaction. Send the transaction id that was created for the previous redemption transaction. IMPORTANT: Send the transaction id of the latest adjustment if there were any adjustments made prior to this request. |
| reason required | string The textual description for why the redemption was done. This text may be presented to the member in their transaction history. While any string length is accepted, 26 characters or less is typically optimal to explain to the member in their transaction history why this redemption was done. Please note that some partners may provide a specific format for this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object JSON object. Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as information about the store, information about the member, entity redeeming the currency, partner codes, connectivity information, or anything else that could be helpful for connections, analytics, or reporting. |
{- "loyalty_system_data": { },
- "metadata": {
- "foo": "bar"
}, - "previous_external_reference": "abcd1234",
- "previous_transaction_id": "tx_abc12312345",
- "reason": "string"
}{- "member": {
- "additional_information": null,
- "address_line1": "3532 Hidden Valley Road",
- "address_line2": "Williamsburg,",
- "address_line3": "Brooklyn",
- "balance": 38250,
- "bank_accounts": {
- "id": "M12334532"
}, - "birth_date": "2000-01-01",
- "city": "New York City",
- "country": "USA",
- "email": "foo@bar.com",
- "first_name": "Barbara",
- "gender": "female",
- "id": "mp_abc123",
- "last_name": "Drennen",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_program_identifiers": {
- "id": "M12334532"
}, - "loyalty_system_balance": "38250.00",
- "phone_number": "+443031237300",
- "postal_code": 11219,
- "state": "New York",
- "tier": {
- "id": "gold",
- "level": 1,
- "name": "gold"
}, - "type": "individual"
}, - "metadata": {
- "foo": "bar"
}, - "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}The Exchange Endpoints enables you to allow your members to exchange their Loyalty Currency Units with your partners' Loyalty Currency Units. You can have a different Exchange Partnership with each Exchange Partner, where you could allow exchange IN or OUT of your currency. The exchange price and other settings are established during the Exchange Partnership set up in the Management Dashboard.
Note that the currencies to be exchanged could be present in different regions and fiat currencies. Currency Alliance will do the currency conversion for the fiat currencies based on the mid-day exchange rate between the fiat currencies.
This Endpoint is typically used in scenarios where you'd want to show to your member that how many units of other currency they would get in exchange for your Loyalty Currency Units or vice versa. For example, if you allow a user to select the number of units of your Loyalty Currency to exchange with your partner's Loyalty Currency, you can use this Endpoint to dynamically show how many units of your partner's Loyalty Currency will be provided to the user for the selected number.
You can send a specific Loyalty Currency as a destination to identify the number of units of that specific Loyalty Currency. Or you could send the destination Loyalty Currency as null and the system will return the array with the exchange result for all the Exchange Partners’ Loyalty Currencies.
Note that the member information is not mandatory but is highly recommended to be input as the exchange price/cost might be dependent on the member attributes.
| amount required | integer Number of origin currency units to be exchanged. |
| origin_loyalty_currency required | string The Currency Identifier of the Origin Loyalty Currency. |
| destination_loyalty_currency | string The Currency Identifier of the Destination Loyalty Currency. This is a unique shortcode Currency Identifier assigned to each currency; it can be found in the 'My Currency' section under 'About My Currency' screen in the Management Dashboard. For the Currency Identifier for your partners' currencies refer to the 'My Partners' section in the Management Dashboard. |
| destination_member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| origin_member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
{- "amount": 500,
- "destination_loyalty_currency": "SST",
- "destination_member": {
- "id": "M12334532"
}, - "loyalty_system_data": { },
- "origin_loyalty_currency": "TSS",
- "origin_member": {
- "id": "M12334532"
}
}{- "SST": 100,
- "STS": 200
}This Endpoint is used to exchange Loyalty Currency Units with your partner’s Loyalty Currency Units. The prerequisite is that an Exchange Partnership is already established in the Management Dashboard and the price is set up accordingly. This Endpoint will automatically create two transactions with type "Member Exchange" in the system.
DO NOT USE the "Create a transaction" Endpoint to try to execute this scenario.
| amount required | integer Number of origin currency units to be exchanged. |
| destination_loyalty_currency required | string The Currency Identifier of the Destination Loyalty Currency. This is a unique shortcode Currency Identifier assigned to each currency; it can be found in the 'My Currency' section under 'About My Currency' screen in the Management Dashboard. For the Currency Identifier for your partners' currencies refer to the 'My Partners' section in the Management Dashboard. |
| destination_member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| origin_loyalty_currency required | string The Currency Identifier of the Origin Loyalty Currency. |
| origin_member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
{- "amount": 500,
- "external_reference": "string",
- "destination_loyalty_currency": "TCC",
- "destination_member": {
- "id": "M12334532"
}, - "loyalty_system_data": { },
- "origin_loyalty_currency": "TSS",
- "origin_member": {
- "id": "M12334532"
}
}{- "origin_transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}, - "destination_transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}| amount required | integer Number of origin currency units to be exchanged. |
| origin_member required | object To be provided while Exchanging OUT from the partner loyalty program. This is the member identifier in your loyalty program from which the points/miles are to be redeemed. The Currency Alliance system will fetch the partner loyalty program account linked to this member account. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
{- "amount": 500,
- "loyalty_system_data": { },
- "origin_member": {
- "id": "M12334532"
}
}{- "SST": 100,
- "STS": 200
}| amount required | integer Number of origin currency units to be exchanged. |
| destination_loyalty_currency required | string To be provided while Exchanging OUT from the partner loyalty program. The Currency Alliance system will automatically identify the member details in the partner program based on the account linked to your member’s account. Loyalty Currency Identifier of the linked Partner Loyalty program. This is a unique shortcode Currency Identifier assigned to each currency; it can be found in the 'My Currency' section under 'About My Currency' screen in the Management Dashboard. For the Currency Identifier for your partners' currencies refer to the 'My Partnerships' section in the Management Dashboard. |
| origin_member required | object To be provided while Exchanging OUT from the partner loyalty program. This is the member identifier in your loyalty program from which the points/miles are to be redeemed. The Currency Alliance system will fetch the partner loyalty program account linked to this member account. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
{- "amount": 500,
- "external_reference": "string",
- "destination_loyalty_currency": "TCC",
- "loyalty_system_data": { },
- "origin_member": {
- "id": "M12334532"
}
}{- "origin_transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}, - "destination_transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}These Endpoints are used for redemption via Gift cards. These Endpoints could be used to retrieve a particular Gift Card, to retrieve a list of enabled Gift cards, to simulate an exchange of currency units for a Gift card, to exchange currency units for a Gift card, or to redeem a custom Gift card. The gift card exchange feature for the loyalty currency must be enabled in the following section of the Management Dashboard: Redemptions > Gift Card Management
There are two objects in the system that represent a Gift card - GiftCard Object and GiftCardCode Object. GiftCard Object represents the general characteristics of the Gift card whereas GiftCardCode Object represents the characteristics that are specific to the Gift card issued to a member.
For example, if a currency owner enables Starbucks gift card through the Management Dashboard there will be a GiftCard Object in our system that would represent general details of Starbucks cards including the possible denominations of let's say $5, $10, $15, $25. When a member exchanges their points for a Starbucks gift card, the system will create a GiftCardCode object specific for that member with specific information such as the value of the Gift card ($5).
GiftCard Object represents a Gift card that could be used for redemption of Loyalty Currency units via Gift cards. It contains the details of the general characteristics of the Gift card. Note that it doesn't represent an issues/redeemed Gift card but only the general characteristics. Once a Gift card is issued GiftCardCode Object provides the details specific to the Gift card for the member. It has the following attributes:
| barcode_format | string Enum: "code-128" "code-39" "ean-13" "pdf417" "QR" null This field identifies the format of the barcode, if present, of the Gift card. Sometimes Gift cards do not have bar codes and thus this field is null; if there exists a value for this field, then the Gift card could be redeemed using the barcode. |
| countries | Array of strings ISO 3166-1 alpha-3 of the countries |
| currency | string Fiat currency in which the Gift card is valued. |
| custom_settings_data | object |
| denomination_type | string Enum: "open" "open_integer" "fixed"
|
| denominations | Array of strings <decimal> [ items <decimal > ] List of available denominations for the Gift card; if the denomination_type field is |
| description | string Text description of the Gift card. |
| discount_value | number <float> |
| expiration_policy | string Text description of expiry policy. |
| id | string Unique identifier for each Gift card. It can be found in the "More Detail" modal of the gift card in the following section in the Management Dashboard Redemptions > Gift Card Management |
| image | string <uri> URL to the image of the card |
| maximum_value | string <decimal> Maximum amount of the gift card. |
| minimum_value | string <decimal> Minimum amount of the gift card. |
| name | string Name of the Gift card |
| provider | string Enum: "currency_alliance" "merit" "wegift" |
| redeem_instructions_html | string HTML formatted product redeem instructions. |
| terms_and_conditions_html | string HTML formatted terms and conditions. |
| terms_and_conditions_url | string URL, if present, to the terms and conditions of the Gift |
| type | string Enum: "discount" "fixed_value" "other" |
{- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}GiftCardCode Object represents the code details for the issued Gift card. It contains information specific to the Gift card issued to the member. For example, in general, Starbucks Gift cards could be of any one of denominations of $5, $10, $25, $50. This Object will provide the exact amount of the Gift card that was issued to the user. It has the following attributes:
| barcode_format | string or null Enum: "code-128" "code-39" "ean-13" "pdf417" "QR" null This field identifies the format of the barcode in the issued Gift card. |
| barcode_string | string String representation of the barcode of the Gift card. |
| delivery_url | string URL where the member can retrieve their card. |
| discount_amount | number <float> |
| expiration_date | string <date> Date when the Gift card expires. |
| fiat_amount | string <decimal> The amount of the Gift card. |
| fiat_balance | string <decimal> |
| fiat_currency | string The fiat currency for the amount of the Gift card. |
| gift_card_code | string Code of the Gift card; the code will be visible to the user. |
| id | string Unique internal identifier generated by the system for each issued Gift card. This identifier should be used to reference a specific Gift card issued/redeemed by a member. |
object | |
| pin | string Represents the pin code of the Gift card. Some Gift cards have a pin code associated with them as part of security for a member to be able to use that Gift card. |
| redemption_details | list |
| redemption_status | string or null Enum: "partially_redeemed" "redeemed" "unredeemed" Redemption status of the giftcard |
{- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}This Endpoint can be used to retrieve the list of gift cards that have been enabled in the following Management Dashboard section:
Redemptions > Gift Card Management
| country | string <[ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the countries> Example: country=USA |
| fiat_currency | string <[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code of the fiat currency> Example: fiat_currency=EUR |
| gift_card_type | string Enum: "discount" "fixed_value" "other" Example: gift_card_type=fixed_value |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}
]
}Returns the general characteristics and details of the specified gift card. The Gift card exchange feature for the loyalty currency must be enabled in the below mentioned section of the Management Dashboard to be able to retrieve information about the Gift card.
Redemptions > Gift Card Management
| id required | string |
{- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}This Endpoint is used in scenarios where one might want to simulate an exchange of Loyalty currency units for a Gift card without actually issuing the Gift card. For example, if a member wants to know how many Loyalty Currency units would be required to exchange for a $5 Starbucks card. This does not result in issuance of a Gift card. The amount can be provided either in units in the field "amount" or in fiat currency in the field "fiat_amount".
The Gift card exchange feature for the loyalty currency must be enabled in the following section of the Management Dashboard:
My Currencies > My Own Currency > Settings > Exchange to Gift Cards
| id required | string |
| fiat_amount required | string <decimal> Amount of the selected gift card in fiat currency. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
{- "fiat_amount": "10.00",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}
}{- "code": {
- "fiat_amount": "20.02",
- "fiat_currency": "EUR"
}, - "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}
}This Endpoint is used to exchange Loyalty currency units for a Gift card. This Endpoint results in issuance of a Gift card. The amount can be provided either in units in the field "loyalty_amount" or in fiat currency in the field "gift_card_amount".
The Gift card issue feature for the loyalty currency must be enabled in the following section of the Management Dashboard:
My Currencies > My Own Currency > Settings > Exchange to Gift Cards
| id required | string |
| fiat_amount required | string <decimal> Amount of the selected gift card in fiat currency. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
{- "external_reference": "string",
- "fiat_amount": null,
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}
}{- "code": {
- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}, - "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}, - "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}| id required | string |
| external_reference required | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| fiat_amount required | string <decimal> Amount of the selected gift card in fiat currency. |
| custom_settings_data | object |
| loyalty_amount_exchanged | integer |
| loyalty_currency | string |
| member_id | string |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| partner_code | string |
{- "custom_settings_data": { },
- "external_reference": "string",
- "fiat_amount": null,
- "loyalty_currency": "string",
- "loyalty_amount_exchanged": 0,
- "member_id": "string",
- "metadata": {
- "foo": "bar"
}, - "partner_code": "string"
}{- "code": {
- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}, - "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}
}| gift_card_code required | string |
| pin | string |
{- "gift_card_code": "string",
- "pin": "string"
}{- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}| channel required | string Enum: "store" "online" Channel of the redemption |
| gift_card_code required | string Code of the gift card to redeem |
| brand_id | string Brand identifier |
| custom_settings_data | object |
| fiat_amount | string <decimal> Amount to redeem from the gift card |
{- "brand_id": "string",
- "channel": "store",
- "custom_settings_data": { },
- "fiat_amount": "20.02",
- "gift_card_code": "ABCD-0000-ABCD-0000"
}{- "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}, - "code": {
- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}
}| channel required | string Enum: "store" "online" Channel of the redemption |
| external_reference required | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| gift_card_code required | string Code of the gift card to redeem |
| brand_id | string Brand identifier |
| custom_settings_data | object |
| fiat_amount | string <decimal> Amount to redeem from the gift card |
| member | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
{- "brand_id": "string",
- "channel": "store",
- "custom_settings_data": { },
- "external_reference": "string",
- "fiat_amount": "20.02",
- "gift_card_code": "ABCD-0000-ABCD-0000",
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}
}{- "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}, - "code": {
- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}
}| gift_card_code | string Code of the gift card to redeem |
{- "gift_card_code": "ABCD-0000-ABCD-0000"
}{- "gift_card": {
- "barcode_format": "QR",
- "countries": [
- "USA"
], - "currency": "USD",
- "custom_settings_data": { },
- "denomination_type": "fixed",
- "denominations": [
- "5.11",
- "10.00",
- "10.01",
- "12.34"
], - "description": "<p>Lorem Ipsum Dolor Amet.</p>",
- "discount_value": 0.1,
- "expiration_policy": "8 months",
- "id": "gcb_TEST",
- "image": null,
- "maximum_value": "100",
- "minimum_value": "10",
- "name": "TEST",
- "provider": "wegift",
- "redeem_instructions_html": "Lorem ipsum dolor sit amet.",
- "terms_and_conditions_html": "<p>Lorem ipsum dolor sit amet.</p>",
- "terms_and_conditions_url": "example.com/conditions.pdf",
- "type": "discount"
}, - "code": {
- "barcode_format": null,
- "barcode_string": null,
- "discount_amount": 0.1,
- "delivery_url": null,
- "expiration_date": "2038-01-19",
- "fiat_amount": "20.02",
- "fiat_balance": "20.02",
- "fiat_currency": "USD",
- "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "issuance_details": {
- "custom_settings_data": { },
- "external_reference": "string",
- "loyalty_information": {
- "loyalty_amount": 0,
- "loyalty_currency": "string",
- "member_id": "string",
- "partner_name": "string"
}, - "metadata": { },
- "original_external_reference": "string",
- "original_code": "string",
- "partner_code": "string"
}, - "pin": null,
- "redemption_details": null,
- "redemption_status": null
}
}Partners Endpoints are used to retrieve information about Partners and specific Partnerships with those Partners. These Endpoints provide information such as Company Name, Logos, Loyalty Currency Information, the terms of the partnership(s), actions available, and the required fields for the actions available. This information can be used to drive different UX paths and to automate API calls.
This Endpoint will be used to either get the list of all the Partners or details about a specific Partner. This Endpoint provides a Partner overview without providing the details of each type of Partnership that you may have with each Partner. The response provides information such as Partner ID, Company Name, Logo, Loyalty Currency Information, and what type of Partnerships are active. The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners.
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "active_partnerships": {
- "exchange_in": true,
- "exchange_out": true,
- "redemption": true,
- "issuing": true,
- "currency_owner_for_issuance": true,
- "currency_owner_for_redemption": true
}, - "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234"
}
]
}This Endpoint is used to either get the list of the Exchange In Partners or details about a specific Exchange In Partner. This Endpoint provides the details of the partners who can Exchange IN to my currency. The response provides information such as Partner ID, Company Name, Logo, Loyalty Currency Information, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners.
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": {
- "exchange_enabled": true
}
}
]
}This Endpoint is used to either get the list of the Exchange Out Partners or details about a specific Exchange Out Partner. This Endpoint provides the details of the partners where I can Exchange OUT from my currency to their currency. The response provides information such as Partner ID, Company Name, Logo, Loyalty Currency Information, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners.
| language_display | string ISO 639-1 of the language you want name of the |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": {
- "batch_process": false,
- "conversion_ratio_per_unit": "1.2",
- "exchange_enabled": true,
- "execute_action": {
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}, - "maximum_member_transaction_amount": 100,
- "member_lookup_action": {
- "member_lookup_available": true,
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}, - "minimum_member_transaction_amount": 10
}
}
]
}This Endpoint is used to either get the list of all the Issuing Partners or details about a specific Issuing Partner that is issuing your Loyalty Currency. This Endpoint provides the details of the Issuing Partnership with each Partner. The response provides information such as Partner ID, Company Name, Logo, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners. Generally, Issuing Partners will not have their own Loyalty Currency, hence, send the value in the Partner ID input parameter in that case.
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": { }
}
]
}This Endpoint is used to either get the list of all the Redemption Partners or details about a specific Redemption Partner that is accepting your Loyalty Currency as a mode of payment or redemption for its products or services. This Endpoint provides the details of the Redemption Partnership with each Partner. The response provides information such as Partner ID, Company Name, Logo, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners. Generally, Redemption Partners will not have their own Loyalty Currency, hence, send the value in the Partner ID input parameter in that case.
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": {
- "adjustment_allowed": false
}
}
]
}This Endpoint is used to either get the list of all the Currency Owner Partners or details about a specific Redemption Currency Owner Partner for redemption i.e. the Currency Owner(s) whose Loyalty Currency you are accepting as payment in exchange for your products or services. This Endpoint provides the details of the Redemption Currency Partnership with each Partner. The response provides information such as Partner ID, Company Name, Logo, Loyalty Currency Information, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners.
| language_display | string ISO 639-1 of the language you want name of the |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": {
- "adjustment_allowed": false,
- "member_lookup_action": {
- "member_lookup_available": true,
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}, - "execute_action": {
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}
}
}
]
}This Endpoint will be used to either get the list of all the Currency Owner Partners or details about a specific Currency Owner Partner for issuance i.e. the Currency Owner whose Loyalty Currency you are issuing to its members. This Endpoint provides the details of the Issuance Currency Partnership with each Partner. The response provides information such as Partner ID, Company Name, Logo, Loyalty Currency Information, and Partnership details including minimum and maximum transaction size, actions available, fields required, etc.
The Endpoint has two input parameters, both optional. Provide a value in either one of the fields if you want to retrieve information about a specific Partner. If no value is provided in either parameter, the system will return a list of all the active partners.
| language_display | string ISO 639-1 of the language you want name of the |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
| partner_id | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "company_name": "XYZ International",
- "loyalty_currency": {
- "id": "EXAMPLE_POINTS",
- "name": "XYZ Rewards Points"
}, - "partner_country": "USA",
- "partner_id": "part_abcd1234",
- "partnership_details": {
- "batch_process": false,
- "execute_action": {
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}, - "loyalty_rules_execution_mode": "multiple_transactions",
- "member_lookup_action": {
- "member_lookup_available": true,
- "required_fields": [
- {
- "id": "card_number",
- "name": "Loyalty Card number"
}
]
}
}
}
]
}This Endpoint is used to convert any fiat currency into a loyalty currency. If the underlying fiat currency of the loyalty currency is different than the requested fiat currency, Currency Alliance will do the currency conversion for the fiat currencies based on the mid-day exchange rate.
An example scenario where this Endpoint is used is when an Issuing Partner may want to offer Currency units worth a specific amount of economic value to a member, but they don´t know how many units of a destination currency can be obtained for that amount of fiat currency. For example, if a partner wants to give 2.43€ worth of value, they can submit that amount via this Endpoint with the desired destination currency and obtain the maximum number of units in that destination currency that can be obtained with 2.43€
| amount required | string <decimal> |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_currency required | string This is the loyalty currency identifier. It is a unique shortcode Currency Identifier assigned to each currency; it can be found in the 'My Currency' section under 'About My Currency' screen in the Management Dashboard. For the Currency Identifier for your partners' currencies refer to the 'My Partners' section in the Management Dashboard. |
| custom_value | string <decimal> |
| custom_value_currency | string ISO 4217 code of the fiat currency |
| price_type | string Default: "customers_perceived_value" Enum: "base_economic_value" "custom_value" "customers_perceived_value" "default_redemption_partners_value" "issuing_partners_cost" |
| rounding | string Default: "bankers_rounding" Enum: "bankers_rounding" "round_up" "round_down" |
{- "amount": "10.00",
- "fiat_currency": "USD",
- "loyalty_currency": "FOO",
- "price_type": "base_economic_value",
- "rounding": "bankers_rounding",
- "custom_value": "10.12345678",
- "custom_value_currency": "USD"
}{- "exact_fiat_cost": "99.0000",
- "loyalty_amount": 10,
- "loyalty_system_amount": "0.10"
}This Endpoint is used to retrieve information about gift card codes that have been issued to partner loyalty programs. This only returns the information of the custom gift cards for which you have provided the gift card codes in advance to the Currency Alliance system.
| created_at__range | string <YYYY-MM-DD[Thh:mm[:ss][Z]],YYYY-MM-DD[Thh:mm[:ss][Z]]> Example: created_at__range=2020-05-02,2020-06-04T09:35:25Z Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date. |
| fiat_currency | string ISO 4217 code of the fiat currency |
| gift_card_id | string |
| loyalty_currency | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "expiration_date": "2038-01-19",
- "fiat_amount": "10",
- "fiat_currency": "USD",
- "gift_card": {
- "id": "gcb_TEST",
- "name": "TEST"
}, - "gift_card_code": "1234-ABCDEF-5678",
- "id": "gcc_abc123",
- "partner": {
- "id": "part_abcd1234",
- "company_name": "Currency Alliance",
- "loyalty_currency": {
- "id": "string",
- "short_name": "string"
}
}, - "pin": null,
- "redemption_status": null
}
]
}This Endpoint is used to retrieve the inventory status of gift card codes of all the custom gift cards for which you have provided the gift card codes in advance to the Currency Alliance system.
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "id": "gcb_TEST",
- "denominations": {
- "5.0": {
- "available": 5,
- "issued": 5,
- "total": 15,
- "unavailable": 5
}
}, - "fiat_currency": "USD",
- "name": "Test gift card",
- "total_codes": 10
}
]
}This Endpoint is used to retrieve the inventory status of gift card codes of a specific custom gift card for which you have provided the gift card codes in advance to the Currency Alliance system.
| id required | string |
{- "id": "gcb_TEST",
- "denominations": {
- "5.0": {
- "available": 5,
- "issued": 5,
- "total": 15,
- "unavailable": 5
}
}, - "fiat_currency": "USD",
- "name": "Test gift card",
- "total_codes": 10
}Retrieve the csv report of the exchange out transactions done by members during a specified time duration. Use the List Transactions endpoint for the report in the standard JSON format.
| created_at__range | string <YYYY-MM-DD[Thh:mm[:ss][Z]],YYYY-MM-DD[Thh:mm[:ss][Z]]> Example: created_at__range=2020-05-02,2020-06-04T09:35:25Z Provide the date range, in the format of two dates separated by a comma, to filter the items based on when when they were created. The first value is the starting date and the second value is the end date. The end date is optional if you want to retrieve all the items since the starting date. |
created_at,destination_amount,destination_loyalty_currency,destination_id,destination_member,external_reference,origin_amount,origin_loyalty_currency,origin_id,origin_member 2019-03-04T11:50:03+0000,10,EXAMPLE_POINTS,tx_abcd1234,M12334532,foo,20,EXAMPLE_POINTS,tx_abcd1234,M12334532
Retrieve cohorts.
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "api_identifier": "part_deprecated",
- "id": "part_abc123",
- "company_name": "FooBar",
- "status": "enabled"
}
]
}Create a cohort. This feature is only available for Loyalty Currency owners.
| company_name required | string |
| status | string Enum: "enabled" "disabled" |
{- "company_name": "FooBar",
- "status": "enabled"
}{- "api_identifier": "part_deprecated",
- "id": "part_abc123",
- "company_name": "FooBar",
- "status": "enabled"
}Updates the information of an existing cohort.
| cohort_id required | string Cohort id. |
| company_name required | string |
| status | string Enum: "enabled" "disabled" |
{- "company_name": "FooBar",
- "status": "enabled"
}{- "api_identifier": "part_deprecated",
- "id": "part_abc123",
- "company_name": "FooBar",
- "status": "enabled"
}Retrieve the accounts of the specified cohort
| cohort_id required | string Cohort id. |
| page | integer Provide value to retrieve the exact page of results. If no value is provided, the system will return the first page. |
| page_size | integer [ 1 .. 500 ] Default: 50 Provide a value between 1 to 500 to return the number of result items on each page. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "id": "acc_abc123",
- "balance": 12345,
- "loyalty_currency": "LLL",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}
]
}List a cohort's activity loyalty rules
| cohort_id required | string Cohort id. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "activity_identifier": "birthday",
- "id": "rl_abc123",
- "loyalty_currency": "LLL",
- "name": "Activity Rule #1",
- "reason": "Lorem Ipsum"
}
]
}| cohort_id required | string Cohort id. |
| rule_id required | string Loyalty rule id. |
| enabled | boolean |
{- "enabled": true
}{- "activity_identifier": "birthday",
- "id": "rl_abc123",
- "loyalty_currency": "LLL",
- "name": "Activity Rule #1",
- "reason": "Lorem Ipsum"
}Simulates the execution of the enabled cohort activity loyalty rules matching the received activity identifier.
The purchase loyalty rules can be defined at the following section: Loyalty Rules > Activity Rules
| cohort_id required | string Cohort id. |
| activity_ids required | Array of strings Unique identifiers defined for each activity for the Loyalty Currency. Refer to the Activity rule in the Management Dashboard Section Loyalty Rules > Activity Rules for this field. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will truncated to the minute. |
{- "activity_ids": [
- "birthday"
], - "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "release_date": "2020-10-10T12:12"
}{- "total": 0,
- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "name": "Activity Rule #1"
}
}
]
}Executes the enabled cohort activity loyalty rules matching the received activity identifier.
The purchase loyalty rules can be defined at the following section: Loyalty Rules > Activity Rules
| cohort_id required | string Cohort id. |
| activity_ids required | Array of strings Unique identifiers defined for each activity for the Loyalty Currency. Refer to the Activity rule in the Management Dashboard Section Loyalty Rules > Activity Rules for this field. |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will truncated to the minute. |
{- "activity_ids": [
- "birthday"
], - "external_reference": "string",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "release_date": "2020-10-10T12:12"
}{- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "name": "Activity Rule #1"
}, - "transaction": {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
}
], - "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}List a cohort's purchase loyalty rules
| cohort_id required | string Cohort id. |
{- "count": 10,
- "next": "?page=2",
- "previous": null,
- "results": [
- {
- "id": "rl_abc123",
- "loyalty_currency": "LLL",
- "name": "Purchase Rule #1",
- "reason": "Lorem Ipsum",
- "tags": [
- "promo20"
]
}
]
}| cohort_id required | string Cohort id. |
| rule_id required | string Loyalty rule id. |
| enabled | boolean |
{- "enabled": true
}{- "id": "rl_abc123",
- "loyalty_currency": "LLL",
- "name": "Purchase Rule #1",
- "reason": "Lorem Ipsum",
- "tags": [
- "promo20"
]
}Simulates the execution of the enabled cohort loyalty rules matching the purchase from the specified member.
The purchase loyalty rules can be defined at the following section: Loyalty Rules > Purchase Rules
| cohort_id required | string Cohort id. |
| fiat_amount required | string <decimal> Amount of the purchase in decimal format. |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| preferred_execution_mode | string Enum: "single_transaction" "multiple_transactions" This field identifies if there are multiple loyalty rules to be executed based on the purchase details, the system should combine all the rules and create only one transaction or execute each rule separately to create a corresponding transaction. The default mode, and recommended, is `multiple_transactions. However, note that some partner loyalty systems may not allow multiple transactions. For such loyalty partners, the Currency Alliance platform will automatically override this field to create "single_transaction". |
| reason | string This field can be used when the preferred_execution_mode is single_transaction. You can provide a combined reason for all the purchase rules that are executed as a single transaction. If no value is provided, the Currency Alliance system will concatenate the reason for each purchase rule. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will be truncated to the minute. |
| tags | Array of strings List of tags. Only the rules that either have no tags or at least one of these tags will be executed. |
{- "external_reference": "string",
- "fiat_amount": "20.00",
- "fiat_currency": "USD",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "preferred_execution_mode": "single_transaction",
- "reason": "string",
- "release_date": "2020-10-10T12:12",
- "tags": [
- "promo20"
]
}{- "total": 0,
- "rules": [
- {
- "amount_issued": 0,
- "rule": {
- "id": "rl_abcd1234",
- "is_bonus": false,
- "name": "Purchase Rule #1"
}
}
]
}Executes the enabled cohort loyalty rules matching the purchase from the specified member.
The purchase loyalty rules can be defined at the following section: Loyalty Rules > Purchase Rules
| cohort_id required | string Cohort id. |
| fiat_amount required | string <decimal> Amount of the purchase in decimal format. |
| fiat_currency required | string ISO 4217 code of the fiat currency |
| loyalty_currency required | string This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information. |
| member required | object This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name. |
| external_reference | string A unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field. |
| loyalty_system_data | object This parameter requires you to send additional information to connect to the loyalty program. For example, user_id, application_id, partner_code, etc. The Partners Endpoint provides the details on which data fields are mandatory inside this parameter. |
| metadata | object Allows up to 5 levels of nesting depth. This data content can include information about the purchase such as items included, information about the store, information about the member, or anything else that could be helpful for analytics and reporting. |
| preferred_execution_mode | string Enum: "single_transaction" "multiple_transactions" This field identifies if there are multiple loyalty rules to be executed based on the purchase details, the system should combine all the rules and create only one transaction or execute each rule separately to create a corresponding transaction. The default mode, and recommended, is `multiple_transactions. However, note that some partner loyalty systems may not allow multiple transactions. For such loyalty partners, the Currency Alliance platform will automatically override this field to create "single_transaction". |
| reason | string This field can be used when the preferred_execution_mode is single_transaction. You can provide a combined reason for all the purchase rules that are executed as a single transaction. If no value is provided, the Currency Alliance system will concatenate the reason for each purchase rule. |
| release_date | string <ISO 8601> Future date on which the Loyalty Currency Units should be made available to the member. The Loyalty Currency Units would be reserved for the member but not made available till the release date is reached. This is used in scenarios such as hotel bookings or flight purchases that are done before the trip so that the member doesn’t redeem the points until they’ve actually stayed at the hotel or flown in the booked flight. The transaction will be created with the status as "pending" and it can be updated or cancelled until the release date. Values with seconds are accepted, but will be truncated to the minute. |
| tags | Array of strings List of tags. Only the rules that either have no tags or at least one of these tags will be executed. |
{- "external_reference": "string",
- "fiat_amount": "20.00",
- "fiat_currency": "USD",
- "loyalty_currency": "EXAMPLE_POINTS",
- "loyalty_system_data": { },
- "member": {
- "id": "M12334532"
}, - "metadata": {
- "foo": "bar"
}, - "preferred_execution_mode": "single_transaction",
- "reason": "string",
- "release_date": "2020-10-10T12:12",
- "tags": [
- "promo20"
]
}{- "id": "pre_abcd1234",
- "total": 0,
- "transactions": [
- {
- "amount": 250,
- "bonus": false,
- "completed_at": "2019-03-04T11:50:03+0000",
- "created_at": "2019-03-04T11:50:03+0000",
- "destination_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "external_reference": "string",
- "id": "tx_abc12312345",
- "loyalty_system_data": { },
- "loyalty_system_id": "string",
- "loyalty_currency": "LLL",
- "metadata": {
- "foo": "bar"
}, - "origin_account": {
- "id": "acc_abc123",
- "owner": {
- "id": "mp_abc123",
- "type": "partner"
}
}, - "reason": "present",
- "reason_code": "string",
- "related_data": {
- "activity_id": "birthday",
- "id": "lr_abcr1234",
- "name": "Activity Rule #1",
- "type": "activity_rule"
}, - "release_date": "2447-12-01T21:56:57Z",
- "status": "pending",
- "status_message": "The release date has not been reached.",
- "status_message_code": "release_date_not_reached",
- "sub-type": "activity_rule",
- "type": "transfer"
}
]
}