GiftCard Partners

B2B API Reference

Complete endpoint documentation for the B2B API (v1).

API docs by Redocly

B2B API (v1)

Download OpenAPI specification:

Deposit Account Balance

  • Your Deposit Account must have sufficient funds to cover an order. To increase your Deposit Account Balance, submit a funding requests through the portal.
  • Your Balance is comprised of a Pending portion and an Available portion. When we receive a funding request, the Pending portion of the balance will increase.
  • When we receive your funds and apply them to your account, the funds will move from Pending to Available for use.

Error Handling

  • In the event of a timeout or disconnect of some sort when you're placing an order, you can either simply retry the order, or do a GET on your previous orders.
  • When retrying an order, ensure that your PO number is the same as your initial attempt.
  • If your initial POST made it through to us and we have your order in our system, you'll receive a 409 Conflict and the response body will contain the Id of your initial order for which you missed the response body.

Caching

  • Endpoints for relatively static data such as Products should be cached for at minimum a week.
  • Most changes to this data will involve alerts from your account manager.

Asynchrony

  • Once a certain order size is reached, the API will respond with your order with a Pending status and then asynchronously complete the order in an effort to make sure that we're able to respond in a timely manner.
  • The API supports webhooks. To be notified when your order has completed processing, provide a FulfillmentComplete webhook setting and our systems will reach out to notify you about your order's updated status.
  • The API supports polling. If you do not wish to accept a webhook for your order status, you may poll for your order status. Your polling frequency should be relative to the size of your order and implement exponential backoffs.

Typical Resource Flow

Tokens

Create a bearer token.

Token creation requires two headers to be present in the request: Email and AccessToken. Note the expiration field. Bearer tokens are meant to be reused for the duration of their lifecycle. Credentials can be provisioned in your user management portal.

Authorizations:
(AccessTokenEmail)

Responses

Response samples

Content type
application/json
{
  • "Value": "string",
  • "ExpiresIn": 0
}

AccountBalance

Get account balance

Authorizations:
Bearer
query Parameters
CurrencyCode
string

Responses

Response samples

Content type
application/json
{
  • "Pending": 750,
  • "Available": 15250,
  • "Departments": [
    ],
  • "CurrencyCode": "USD"
}

Products

Get a particular product

Authorizations:
Bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "Id": "string",
  • "Denominations": [
    ],
  • "ShortDescription": "string",
  • "LongDescription": "string",
  • "Name": "string",
  • "AvailableDeliveryTypes": [
    ],
  • "Terms": "string",
  • "Disclaimer": "string",
  • "RedemptionNote": "string",
  • "Type": "Digital",
  • "DenominationType": "Fixed",
  • "Meta": {
    },
  • "Media": {
    },
  • "Cost": {
    },
  • "Translations": [
    ],
  • "CurrencyCode": "USD",
  • "CultureCodes": [
    ]
}

Get products

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 500 ]
Default: 25
productName
string

Loose matching - will succeed when this value exists in the product name.

productDescription
string

Loose matching - will succeed when this value exists in either the long product description or the short product description.

currencyCode
string
Example: currencyCode=USD

ISO 4217

productType
string (ProductType)
Enum: "Digital" "Physical"

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}

ShippingMethods

Get Shipping Methods

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 50 ]
Default: 5

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}

Carriers

Get Carriers

A carrier is the physical packaging that a card is attached to when shipped. If your account is entitled to anything above and beyond the default carrier, you'll see them listed here.

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 50 ]
Default: 5

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}

Brandings

Get Brandings

A branding is the customization template a digital card is attached to when emailed to the recipient. If your account is entitled to anything above and beyond the default template, you'll see them listed here.

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 50 ]
Default: 5

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}

Orders

Create an order

Authorizations:
Bearer
Request Body schema: application/json
required
Type
required
string (DeliveryType)
Enum: "DigitalDelivery" "PhysicalShipment" "Links"
required
Array of objects (OrderRequestLineItem)
object (OrderPersonalization)
PONumber
required
string [ 1 .. 100 ] characters

Identifier for the order set by the caller. Must be unique.

Note
string or null <= 250 characters

Optional text pass-through.

DepartmentId
string or null <= 50 characters

Id of department that will be associated with the order. Not to be provided unless configured. MUST be provided if configured.

object (OrderRequestWebhookSettings)

Responses

Request samples

Content type
application/json
Example
{
  • "Type": "DigitalDelivery",
  • "LineItems": [
    ],
  • "PONumber": "EX-123-789"
}

Response samples

Content type
application/json
{
  • "Id": "string",
  • "Timestamp": "2020-03-14T01:46:49Z",
  • "Date": "string",
  • "Status": "Pending",
  • "LineItems": [
    ],
  • "CurrencyCode": "USD",
  • "Type": "DigitalDelivery",
  • "Personalization": {
    },
  • "PONumber": "PO-123456789",
  • "Note": "Placed for XYZ recipients",
  • "DepartmentId": "Dept123",
  • "WebhookSettings": {}
}

Get order history

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 50 ]
Default: 5
startDate
string <date-time>
endDate
string <date-time>
poNumber
string
productId
string
recipientName
string
recipientEmail
string
recipientSms
string

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}

Get a particular order

Authorizations:
Bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "Id": "string",
  • "Timestamp": "2020-03-14T01:46:49Z",
  • "Date": "string",
  • "Status": "Pending",
  • "LineItems": [
    ],
  • "CurrencyCode": "USD",
  • "Type": "DigitalDelivery",
  • "Personalization": {
    },
  • "PONumber": "PO-123456789",
  • "Note": "Placed for XYZ recipients",
  • "DepartmentId": "Dept123",
  • "WebhookSettings": {}
}

Status

Validate system connectivity

Authorizations:
Bearer

Responses

Departments

Get Departments

Fetch portal-configured departments (if enabled)

Authorizations:
Bearer
query Parameters
pageIndex
integer <int32> [ 1 .. 2147483647 ]
Default: 1

One based.

pageSize
integer <int32> [ 1 .. 50 ]
Default: 5

Responses

Response samples

Content type
application/json
{
  • "Data": [
    ],
  • "Page": 1,
  • "PageSize": 10,
  • "TotalCount": 53
}