Manage orders

With Tango API, you can manage rewards orders, get a list of orders that have been placed, get details for specific orders, or resend an undelivered order.

❗️

Disclaimer:

When ordering a physical gift card, make sure to validate the physical address of your reward recipients before sending it to Tango. Tango does not accept any responsibilities for the incorrect addresses.

📘

Notes:

• When placing orders, you are responsible to deliver rewards if sendEmail=false. Tango does not deliver the reward email when sendEmail= false.
• If you submit a recipient firstName and emailAddress with a Promo Link order when sendEmail=false, Tango will send out the reminder emails and the reactivation emails when reactivated from the Tango Portal.
• For the best data mapping experience, inspect the credentialList array under the reward block.
• Credentials is a legacy parameter with no data mapping key/value pairs.
• CredentialList contains type, label, and value, and stable parameters that allow our clients to display rewards within an application or by email.
• Order requests receiving a 5XX error may occasionally process after a network connection is lost. We strongly recommend you use the External Reference ID idempotent parameter to ensures duplicate orders are not created when you retry a failed order. See our Best practices content regarding External Reference ID idempotent parameter.

Get a list of orders placed under this platform

Use the following endpoint to get 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.

📘

Note:

When you are searching for an amount, we recommend you to enter a minimum and a maximum amount for search.

The response message for this endpoint is:

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

The following example shows the response including pagination when you use GET {URI}/orders:

{
  "page": {
    "number": 0,
    "elementsPerBlock": 25,
    "resultCount": 25,
    "totalCount": 10000
  },
  "orders": [
    {
      "referenceOrderID": "RA230510-100558-92",
      "customerIdentifier": "string", (5-100 chars)
      "accountIdentifier": "string", (5-100 chars)
      "accountNumber": "A26904565",
      "amountCharged": {
        "value": 1,
        "currencyCode": "string", (3 chars)
        "total": 1
      },
      "utid": "U163059",
      "rewardName": "Amazon.com Gift Card",
      "sender": {
        "firstName": "string", (100 chars)
        "lastName": "string", (100 chars)
        "email": "string", (100 chars)
      },
      "recipient": {
        "email": "string", (100 chars),
        "firstName": "string", (100 chars),
        "lastName": "string", (100 chars),
        "address": null
      },
      "emailSubject": "干得好",
      "message": "string", (10240 chars)
      "sendEmail": true,
      "etid": "E000000",
      "status": "COMPLETE",
      "campaign": "string", (100 chars)
      "createdAt": "2023-05-10T16:33:18.707Z"
    }
}

Create an order under a specific account

Use the following endpoint to create 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. The recipient address object is required for physical rewards. For digital orders, it must be excluded or set to null.

📘

Note:

Providing an address for digital orders will result in validation failure.

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 the response using POST {URI}/orders. Perform the call to order one of the UTIDs that was returned in your GET {URI}/orders call.

{
  "page": {
    "number": 0,
    "elementsPerBlock": 0,
    "resultCount": 0,
    "totalCount": 0
  },
  "orders": [
    {
      "referenceOrderID": "string",
      "externalRefID": "string",
      "customerIdentifier": "string", (5-100 chars)
      "accountIdentifier": "string", (5-100 chars)
      "accountNumber": "string",
      "amountCharged": {
        "value": 0,
        "currencyCode": "string", (3 chars)
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "denomination": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "utid": "string",
      "rewardName": "string",
      "sender": {
        "firstName": "string", (5-100 chars)
        "lastName": "string", (5-100 chars)
        "email": "string"
      },
      "recipient": {
        "email": "string",
        "firstName": "string", (5-100 chars)
        "lastName": "string", (5-100 chars)
        "address": {
          "streetLine1": "string", (200 chars)
          "streetLine2": "string", (100 chars)
          "city": "string", (60 chars)
          "stateOrProvince": "string", (60 chars)
          "postalCode": "string", (12 chars)
          "country": "string" (2 chars)
        }
      },
      "emailSubject": "string",
      "message": "string", (1024 chars)
      "sendEmail": true,
      "etid": "string",
      "status": "string",
      "campaign": "string",
      "createdAt": "2023-09-18T17:18:05.159Z",
      "notes": "string",
      "orderClientSource": "string",
      "purchaseOrderNumber": "string"
    }
  ]
}

Get details for a specific order

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

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

The response message for this endpoint is:

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

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

{
  "referenceOrderID": "string",
  "externalRefID": "string", (100 chars)
  "customerIdentifier": "string", (5-100 chars)
  "accountIdentifier": "string", (5-100 chars)
  "accountNumber": "string", (5-100 chars)
  "amountCharged": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "utid": "string",
  "rewardName": "string",
  "sender": {
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "address": {
      "streetLine1": "string",
      "streetLine2": "string",
      "city": "string",
      "stateOrProvince": "string",
      "postalCode": "string",
      "country": "string"
    }
  },
  "emailSubject": "string",
  "message": "string", (1024 chars)
  "sendEmail": true,
  "etid": "string",
  "status": "string",
  "campaign": "string", (100 chars)
  "createdAt": "2023-09-18T19:36:27.589Z",
  "notes": "string", (150 chars)
  "orderClientSource": "string",
  "purchaseOrderNumber": "string",
  "reward": {
    "credentials": {
      "additionalProp": "string"
    },
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "type": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  }
}

📘

Order history:

Orders placed via the Tango API are v1 available via the v2 GET {URI}/orders call and are combined with Orders placed via the Tango API v2. 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.

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

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

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 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 Tango API v1 are handled in the same fashion as resends of Orders placed via the Tango API v2. Only orders where Tango sent the original email can be resent by Tango . 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 to perform the resend. The Tango 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.