Manage Orders

What is an Order? ,,,,,,

๐Ÿ“˜

Note:

  • Tango Card does not deliver a reward email when sendEmail= false while placing orders. It is our client's responsibility to deliver rewards when sendEmail=false.
  • Inspect the credentialList array under the reward block, for the best data mapping experience.
  • Credentials is a legacy parameter with no data mapping key/value pairs.
  • CredentialList contains type, label, and value, stable parameters that allow our clients to display rewards within an application or by email.

Use Case

(use case here,,,,,)

About External Reference ID

See the following notes regarding External Reference ID:

  • externalRefID is an optional idempotent field. We allow one unique order per External Reference ID. Subsequent requests using the same External Reference ID does not create a new order, but returns the original order information even if the original order is for a different item.
  • IDs have a maximum of 100 alphanumeric characters.
  • If an externalRefID is not provided, the X-REQUEST-ID included in the response header for the transaction is used as a reference to contact Tango Card support on the status of an order.
  • Idempotency is enforced at the account level. We do not check for ID uniqueness in other accounts even if they are under the same Platform or Customer.
  • If you wish to use a non-idempotent field for notes, we recommend you use the optional Notes field.

๐Ÿ“˜

Note:

Tango Card does not support idempotency after 90 days from the original order.

Note that order requests receiving a 5XX error may occasionally process after a network connection is lost. For this reason we strongly recommend you make use of the External Reference ID idempotent parameter to ensures duplicate orders are not created when you retry a failed order.

Get a List of Orders Placed Under this Platform

Use the following endpoint to get a list of orders placed under this platform:

EndpointPurpose
GET {URI}/ordersGet a list of orders placed under this platform.

Here is a list of query parameters for when you use GET {URI}/orders to get a list of orders placed under this platform.

Query ParameterData typeDescription
accountIdentifierStringspecify the account to be queried.
customerIdentifierStringspecify the customer to be queried.
externalRefIDStringspecify the external reference ID to be queried.
See more about External Reference ID.
startDateStringspecify the starting date or date time to be queried according to RFC 3339, i.e. "2016-01-01" or "2016-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
endDateStringspecify the ending date or date time to be queried according to RFC 3339, i.e. "2016-01-01" or "2016-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
elementsPerBlockint32specify the number of elements in a block.
pageint32specify the page number to return.

The response message for this endpoint is:

  • 200 OK
  • 400 Bad request
  • 401 Unauthorized
  • 403 Forbidden

Create an Order Under a Specific Account

Use the following endpoint to create an Order under a specific Account.

EndpointPurpose
POST {URI}/ordersCreate an Order under a specific Account.

Here are a list of body parameters for when you use POST {URI}/orders to create an Order under a specific Account.

Body ParameterData TypeDescription
externalRefID*string(Optional) Idempotenent field that can be used for client-side order cross reference and prevent accidental order duplication. Will be returned in order response, order details, and order history. See more about External Reference ID.
customerIdentifierstring(Required) Specify the customer associated with the order. Must be the customer the accountIdentifier is associated with.
accountIdentifierString(Required) Specify the account this order will be deducted from.
utidstring(Required) The unique identifier for the reward you are sending as provided in the Get Catalog call.
amountnumber(Required) Specify the face value of of the reward. Always required, including for fixed value items.
senderobject(Optional) Use to set the senderโ€™s name and email address if different than the default platform setting.
recipientobject(Required) If sendEmail is true. Use to set and store the recipient name and email address. When sendEmail is false, setting these parameters will allow the platform to store this information for reporting, auditing, and reconciliation.
emailSubjectstring(Optional) If not specified, a default email subject will be used for the specified reward.
messagestring(Optional) gift message
sendEmailboolean(Required) Should Tango Card send the email to the recipient?
etid(Optional) The unique identifier for the email template you would like to use. Only applicable if sendEmail is true.
campaignstring(Optional) Campaign that may be used to administratively categorize a specific order.
notesstring(Optional) Order notes (up to 150 characters)

The response message for this endpoint is:

  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
  • 402 Insufficient Funds
  • 403 Forbidden
  • 503 Service Unavailable

The following example shows how you can create an order using POST {URI}/orders. Perform the call to order one of the UTIDs that was returned in your GET {URI}/orders call.

{
  "accountIdentifier": "accountId",
  "amount": 10,
  "campaign": "",
  "customerIdentifier": "customerId",
  "emailSubject": "",
  "externalRefID": "",
  "message": "",
  "notes": "",
  "recipient": {
    "email": "[email protected]",
    "firstName": "First",
    "lastName": ""
  },
  "sendEmail": true,
  "sender": {
    "email": "",
    "firstName": "",
    "lastName": ""
  },
  "utid": "U561593"
}

Get Details for a Specific Order

Use the following endpoint to retrieve details for a specific Order.

EndpointPurpose
GET {URI}/orders/{referenceOrderID}Get details for a specific order.

Here is the path parameter when you use GET {URI}/orders/{referenceOrderID} to get details for a specific order.

Path ParameterData TypeDescription
referenceOrderIDstringReference order ID is returned in the order response payload

The response message for this endpoint is:

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

The following example shows an order placed in the past. Perform a GET {URI}/orders/{referenceOrderID} call to view the details of an old order you have placed in the system.

{
    "referenceOrderID": "RA123456-7890-12",
    "externalRefID": "",
    "customerIdentifier": "customerId",
    "accountIdentifier": "accountId",
    "accountNumber": "A123456",
    "amountCharged": {
        "value": 10.00,
        "currencyCode": "USD",
        "total": 10.0
    },
    "denomination": {
        "value": 10,
        "currencyCode": "USD"
    },
    "utid": "U561593",
    "rewardName": "Reward Link",
    "sender": {
        "firstName": "",
        "lastName": "",
        "email": ""
    },
    "recipient": {
        "email": "[email protected]",
        "firstName": "First",
        "lastName": "Last"
    },
    "emailSubject": "",
    "message": "",
    "sendEmail": true,
    "etid": "E000000",
    "status": "COMPLETE",
    "campaign": "",
    "createdAt": "2020-12-22T18:23:23.472Z",
    "notes": "",
    "reward": {
        "credentials": {
            "Redemption Link": "https://sandbox.rewardlink.io/r/1/_KBqZ9x056xOCrp34qxM74R2KQqYJlHoaJKZAXbwkSQ",
            "Expiration": ""
        },
        "credentialList": [
            {
                "label": "Redemption Link",
                "value": "https://sandbox.rewardlink.io/r/1/_KBqZ9x056xOCrp34qxM74R2KQqYJlHoaJKZAXbwkSQ",
                "type": "url",
                "credentialType": "redemptionUrl"
            },
            {
                "label": "Expiration",
                "value": "",
                "type": "date",
                "credentialType": "expirationDate"
            }
        ],
        "redemptionInstructions": "<p><a href=\"https://www.rewardsgenius.com/reward-link-terms-of-service/\">Read Terms &amp; Conditions</a></p>\r\n\r\n<ul>\r\n\t<li>Click the redemption link above to activate your Reward Link.</li>\r\n\t<li>Next, you will be able to spend your balance on retail gift cards.</li>\r\n</ul>\r\n\r\n<p>If you don&#39;t want to spend your entire Reward Link value right away, save the email or URL and return via the redemption link before the expiration date provided with your Reward Link.</p>\r\n"
    }
}

๐Ÿ“˜

Order History:

Orders placed via the RaaS v1 API are available via the v2 GET {URI}/orders call and are combined with orders placed via the RaaS v2 API. To retrieve full order details, including reward credentials, make a GET {URI}/orders/{referenceOrderId} call.

Resend a Specific Order

Use the following endpoint to resend a specific Order.

EndpointPurpose
POST {URI}/orders/{referenceOrderID}/resendsResend a specific Order.

Here is the parameters when you use POST {URI}/orders/{referenceOrderID}/resends to resend a specific order:

ParameterData TypeDescription
referenceOrderIDstring(Required) Reference order ID is returned in the order response payload. (path parameter)
newEmailstringA new email to resend this order to. (body parameter)

The response message for this endpoint is:

  • 201 Created
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden

The Resend method allows you to resend reward emails to the original recipient on demand. This may be useful if a recipient reports that they never received the reward email or cannot find it.

The following example shows a past order is resent using POST {URI}/orders/{referenceOrderID}/resends.

{
  "newEmail": "[email protected]"
}

To send the target order (resent), you must set the sendEmail property value to true (default) which means Tango Card has sent the original email. If the property value is set to false, it indicates that we have never sent the original email, therefore, we cannot resend it.

๐Ÿ“˜

Note:

  • Orders can be resent once every 30 seconds. The error message timestamp notifies you if a second attempt is made less than 30 seconds following the last send.
    • Resends of orders placed via the RaaS v1 API are handled in the same fashion as resends of orders placed via the RaaS v2 API. Only orders where Tango Card sent the original email can be resent by Tango Card. If you delivered reward credentials directly to your recipients, you need to retrieve them again via the GET {URI}/orders/{referenceOrderId} call.

You need the original order number in order to perform the resend. The Tango Card Order History call allows searching past orders. The order number is included in the order result.

๐Ÿ“˜

Note:

  • Orders can be resent to a new email address, but to the same recipient. A reward links is tied to the same email address.
  • If an administrator needs to verify reward information for a given order, consider using the Get Order Information call instead of the Resend a Reward Email call.

Resending an email does not guarantee delivery. If the recipient does not receive an email due to spam filter settings, corporate firewalls, etc. resending an email may not be enough. The underlying problem must be determined and resolved.


Whatโ€™s Next