send-gift

POST /api/integration/gifting/send-gift

Create and send a gift to a recipient. Can be used to send monetary or item gifts and for sending promotional or non-promotional gifts.

Common request body structure for all variations:

{  
  "recipients": [  
    {  
      "deliveryMethodID": 0,  
      "recipientDescription": "string",  
      "recipientContact": "string",  
      "message": "string"  
    }  
  ],  
  "monetaryGift": /_ … monetary gift … _/,  
  "itemGift": /_ … item gift … _/,  
  "senderDescription": "string",  
  /_ … payment method fields … _/  
}

The rest of the fields are described below.

Recipient Definition

For a single recipient - you can specify the recipientDescription (ie the recipient name - like "Joe Smith" - or nickname - like “Dad” or “Mom”) and recipientContact (the destination email/mobile number) within the gift definition. For multiple - use the recipients collection and leave the corresponding fields out of the gift definition.

The senderDescription describes who appears as the sender of the gift. For External Purchases, if not specified, this will use external transaction customer name.

Gift Definition

You must specify 1 and only 1 gift definition - either a monetary or item gift.

Monetary Gifts

{  
    "value": 0,  
    "programID": "00000000-0000-0000-0000-000000000000",  
    "accountID": "00000000-0000-0000-0000-000000000000",  
    "organizationID": "00000000-0000-0000-0000-000000000000",  
    "deliveryMethodID": 0,  
    "senderDescription": "string",  
    "recipientDescription": "string",  
    "recipientContact": "string",  
    "message": "string",  
    "hasScheduledDelivery": true,  
    "deliveryDate": "2022-06-27T15:52:05.172Z",  
    "deliveryTimezoneId": "string",  
    "voucherDesignID": "00000000-0000-0000-0000-000000000000"  
}

The programID describes the gifting program. See below for options. The account specified must be subscribed to this gifting program.

The accountID describes the merchant account this gift is good for. If specified and using an account integrations API key - this must match the account associated with the key.

The organizationID describes the specific location this gift is good for (if limiting to a specific location). This field is optional. If specified - it must be a location within the account specified.

The voucherDesignID describes the configuration to use for the look and feel of the delivered gift card. This can be left blank and the system will fall back to the default for the location or account.

Item Gifts

{  
    "label": "string",  
    "terms": "string",  
    "quantity": 0,  
    "equivalentValue": 0,  
    "programID": "00000000-0000-0000-0000-000000000000",  
    "accountID": "00000000-0000-0000-0000-000000000000",  
    "organizationID": "00000000-0000-0000-0000-000000000000",  
    "deliveryMethodID": 0,  
    "senderDescription": "string",  
    "recipientDescription": "string",  
    "recipientContact": "string",  
    "message": "string",  
    "hasScheduledDelivery": true,  
    "deliveryDate": "2022-06-27T15:52:05.172Z",  
    "deliveryTimezoneId": "string",  
    "voucherDesignID": "00000000-0000-0000-0000-000000000000"  
}

See above for general field definitions.

Delivery Method Selection

Use one of the following:

ID	Meaning	Details
1	Email	Specify an email in `recipientContact`.
2	SMS	Specify a 10-digit mobile num in `recipientContact`. (assumes a +1 area code)
3	Printed	Do not specify a `recipientContact`.

To generate a gift that is not delivered or delivery is handled outside of the Gift Local system - use 3 (Printed).

Gifting Program Selection

You’ll need to specify one of the following gift programs:

ID	Description
22222222-2222-2222-2222-222222222222	Business Gift Cards (i.e. C2C / consumer-to-consumer)
33333333-3333-3333-3333-333333333333	Promotional Gift Cards (i.e. B2C / business-to-consumer)
55555555-5555-5555-5555-555555555555	Distribution Network (C2C purchased on partner sites)

If not specified, the system will default to 2X for external transactions and 3X for promotion gifts.

Payment Method Selection

Because gifts have a value, they must be "paid" for. This payment can be captured externally to the Gift Local system (for consumer purchased gifts) or come from a merchants promotional budget. While for this API, Gift Local does not actually capture any payment - it does need to account for how this stored value became available.

Use one of the following:

ID	Description
2	External Transaction Purchased by the consumer on an external system and paid for on that system.
4	Promotional The gift is promotional and no payment was captured or necessary.

Fields for each type are described below.

External Purchase

{  
  /_ … recipient and gift definition … _/  
  "paymentMethodID": 2, /_ this will always be 2 for external purchases _/  
  "externalTransactionReferenceNumber": "string",  
  "externalTransactionCustomerFirstName": "string",  
  "externalTransactionCustomerLastName": "string",  
  "externalTransactionCustomerEmailAddress": "string",  
  "externalStorefrontID": "00000000-0000-0000-0000-000000000000"  
}

The externalTransactionReferenceNumber is a reference number used to track this purchase back to the system where it was purchased.

The externalStorefrontID is the ID of a Gift Local “storefront” record used to track this purchase interface.

Promotional Gift

{  
  /_ … recipient and gift definition … _/  
  "paymentMethodID": 4, /_ this will always be 4 for promotional gifts_/  
  "promotionID": "00000000-0000-0000-0000-000000000000",  
  "validStarting": "2022-06-27T15:52:05.172Z",  
  "validForDays": 0,  
  "promotionalTerms": "string"  
}

The promotionID is the ID of a Gift Local “promotion” record used to track gifts created under this promotional program.