{ "openapi": "3.0.1", "info": { "title": "B2B API", "description": "# Deposit Account Balance\n\n- Your Deposit Account must have sufficient funds to cover an order. To increase your Deposit Account Balance, submit a funding requests through the portal.\n- 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.\n- When we receive your funds and apply them to your account, the funds will move from `Pending` to `Available` for use.\n\n# Error Handling\n\n- 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.](#operation/GetOrders)\n- When retrying an order, ensure that your PO number is the same as your initial attempt.\n- 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.\n\n# Caching\n\n- Endpoints for relatively static data such as [Products](#tag/Products) should be cached for at minimum a week.\n- Most changes to this data will involve alerts from your account manager.\n\n# Asynchrony\n\n- 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.\n- 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.\n- 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.\n\n# Typical Resource Flow\n\n- [Token Exchange](#operation/CreateToken) - Create a Bearer token for authenticating all subsequent calls.\n- [Browse Products](#operation/GetProducts) - Identify and cache orderable products.\n- [Create an Order](#operation/PostOrder) - Create an order.", "version": "v1", "x-logo": { "url": "https://eg-ui-assets.images.egifter.com/brands/sites/BR-E2R/DEFAULT/logo-api.png", "altText": "E2R Logo", "href": "https://engage2reward.com" } }, "servers": [ { "url": "https://api.engage2reward.com", "description": "Production" }, { "url": "https://stage.api.engage2reward.com", "description": "Stage" } ], "paths": { "/v1/Tokens": { "post": { "tags": [ "Tokens" ], "summary": "Create a bearer token.", "description": "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.", "operationId": "CreateToken", "responses": { "200": { "description": "Token successfully generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "AccessToken": [ ], "Email": [ ] } ] } }, "/v1/AccountBalance": { "get": { "tags": [ "AccountBalance" ], "summary": "Get account balance", "description": "", "operationId": "GetAccountBalance", "parameters": [ { "name": "CurrencyCode", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account balance successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountBalance" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get a particular product", "description": "", "operationId": "GetProduct", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "No available product found" }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Products": { "get": { "tags": [ "Products" ], "summary": "Get products", "description": "", "operationId": "GetProducts", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "format": "int32", "default": 25 } }, { "name": "productName", "in": "query", "description": "Loose matching - will succeed when this value exists in the product name.", "schema": { "type": "string" } }, { "name": "productDescription", "in": "query", "description": "Loose matching - will succeed when this value exists in either the long product description or the short product description.", "schema": { "type": "string" } }, { "name": "currencyCode", "in": "query", "description": "ISO 4217", "schema": { "type": "string", "example": "USD" }, "example": "USD" }, { "name": "productType", "in": "query", "schema": { "$ref": "#/components/schemas/ProductType" } } ], "responses": { "200": { "description": "Request successfully executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/ShippingMethods": { "get": { "tags": [ "ShippingMethods" ], "summary": "Get Shipping Methods", "description": "", "operationId": "GetShippingMethods", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "Shipping methods successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingMethodsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Carriers": { "get": { "tags": [ "Carriers" ], "summary": "Get Carriers", "description": "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.", "operationId": "GetCarriers", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "Carriers successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarriersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Brandings": { "get": { "tags": [ "Brandings" ], "summary": "Get Brandings", "description": "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.", "operationId": "GetBrandings", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "Brandings successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Orders": { "post": { "tags": [ "Orders" ], "summary": "Create an order", "description": "", "operationId": "CreateOrder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" }, "examples": { "Create Digital Delivery Order": { "summary": "Digital Delivery - Platform will send digital Gift cards on Client's behalf", "value": {"Type":"DigitalDelivery","LineItems":[{"ProductId":"PRODUCTA","Value":5.0,"Quantity":1,"DigitalDeliveryAddress":{"Email":"user@example.com"},"Personalization":{"To":"Gift Recipient","FromEmail":"sender@example.com","Message":"Enjoy your gift card!"}}],"PONumber":"EX-123-789"} }, "Create Links Order": { "summary": "Links - Platform will provide claim links for Client to distribute", "value": {"Type":"Links","LineItems":[{"ProductId":"PRODUCTA","Value":15.0,"Quantity":1}],"PONumber":"EX-789-123"} }, "Create Links Order - French": { "summary": "Links - Platform will provide claim links in French for Client to distribute", "value": {"Type":"Links","LineItems":[{"ProductId":"PRODUCTA","Value":15.0,"Quantity":1,"Culture":"fr-CA"}],"PONumber":"EX-789-123"} }, "Create Physical Order": { "summary": "Physical Fulfillment - Platform will notify physical fulfiller to ship physical gift cards", "value": {"Type":"PhysicalShipment","LineItems":[{"ProductId":"PRODUCTA","Value":15.0,"Quantity":3,"PhysicalDeliveryAddress":{"ShippingMethodId":"NEXT-DAY-AIR","CarrierId":"Carrier-ID-1","ShipmentId":"Shipment-Group-1","Name":"Gift Recipient","AddressLine1":"315 Main Street","AddressLine2":"Second Floor","City":"Huntington","State":"NY","Zip":"11743","Country":"US"}}],"PONumber":"EX-ABC-789"} } } } }, "required": true }, "responses": { "201": { "description": "Order successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Error in the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "409": { "description": "Duplicate order. PO number must be unique.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictingOrderResponse" } } } }, "422": { "description": "Unprocessable order. Insufficient funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientFundsResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] }, "get": { "tags": [ "Orders" ], "summary": "Get order history", "description": "", "operationId": "GetOrders", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "format": "int32", "default": 5 } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "poNumber", "in": "query", "schema": { "type": "string" } }, { "name": "productId", "in": "query", "schema": { "type": "string" } }, { "name": "recipientName", "in": "query", "schema": { "type": "string" } }, { "name": "recipientEmail", "in": "query", "schema": { "type": "string" } }, { "name": "recipientSms", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order history successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersResponse" } } } }, "400": { "description": "Error in the request" }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get a particular order", "description": "", "operationId": "GetOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "description": "Requested order not found" }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Status": { "get": { "tags": [ "Status" ], "summary": "Validate system connectivity", "operationId": "CheckStatus", "responses": { "200": { "description": "Core system connectivity confirmed" }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } }, "/v1/Departments": { "get": { "tags": [ "Departments" ], "summary": "Get Departments", "description": "Fetch portal-configured departments (if enabled)", "operationId": "GetDepartments", "parameters": [ { "name": "pageIndex", "in": "query", "description": "One based.", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 50, "minimum": 1, "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "Departments successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing or invalid Authorization header" }, "403": { "description": "Access disabled for the account backing this credential set." }, "500": { "description": "Error processing request" }, "504": { "description": "Request timed out" } }, "security": [ { "Bearer": [ ] } ] } } }, "components": { "schemas": { "AccountBalance": { "type": "object", "properties": { "Pending": { "type": "number", "description": "Account funds that are awaiting approval.", "format": "double", "example": 750 }, "Available": { "type": "number", "description": "Account funds that are available for use.", "format": "double", "example": 15250 }, "Departments": { "type": "array", "items": { "$ref": "#/components/schemas/DepartmentBalance" }, "description": "Funds distribution across configured departments.", "nullable": true }, "CurrencyCode": { "type": "string", "description": "Currency of funds", "nullable": true, "example": "USD" } }, "additionalProperties": false }, "BarcodeType": { "enum": [ "None", "Code128", "QR", "PDF417", "Aztec", "ITF", "_2D", "Code39", "Code93" ], "type": "string" }, "Branding": { "required": [ "Id", "Name" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string" }, "Name": { "minLength": 1, "type": "string" } }, "additionalProperties": false }, "BrandingsResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Branding" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "CardholderInformation": { "required": [ "AddressLine1", "City", "Country", "Name", "State", "Zip" ], "type": "object", "properties": { "PhoneNumber": { "type": "string", "description": "Phone number of the cardholder.", "nullable": true, "example": "5554445555" }, "Email": { "type": "string", "description": "Email address of the cardholder.", "nullable": true }, "Name": { "maxLength": 150, "minLength": 1, "type": "string", "description": "Full Name.", "example": "Recipient Name" }, "AddressLine1": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Street and number, P.O. box, c/o.", "example": "315 Main Street" }, "AddressLine2": { "maxLength": 100, "type": "string", "description": "Apartment, suite, unit, building, floor, etc.", "nullable": true, "example": "Second Floor" }, "AddressLine3": { "maxLength": 30, "type": "string", "description": "Typically used as a company name with physical fulfillment partners where supported", "nullable": true }, "City": { "maxLength": 100, "minLength": 1, "type": "string", "description": "City", "example": "Huntington" }, "State": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Two character State / Province / Region code as defined in ISO 3166-2.", "example": "NY" }, "Zip": { "maxLength": 50, "minLength": 1, "type": "string", "description": "Zip / Postal Code.", "example": "11743" }, "Country": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Two character Country / Region code as defined in ISO 3166-2.", "example": "US" } }, "additionalProperties": false }, "Carrier": { "required": [ "Id" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string" }, "Name": { "type": "string", "nullable": true }, "Description": { "type": "string", "nullable": true }, "ProductIds": { "type": "array", "items": { "type": "string" }, "description": "If specified, this carrier can only be used for these specific product ids.", "nullable": true }, "FulfillmentGroup": { "type": "string", "description": "If specified, `FulfillmentGroup` ids must match across `ShippingMethod`, (Product)`ShippingConfiguration`, and `Carrier`.", "nullable": true }, "MinSupportedQuantity": { "type": "integer", "description": "Minimum number of products that can be shipped using this packaging option.", "format": "int32" }, "MaxSupportedQuantity": { "type": "integer", "description": "Maximum number of products that can be shipped using this packaging option.", "format": "int32" }, "Type": { "$ref": "#/components/schemas/ShippingType" } }, "additionalProperties": false }, "CarriersResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Carrier" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "ClaimCode": { "type": "object", "properties": { "Label": { "type": "string", "description": "Label for the code provided.", "nullable": true, "example": "Gift Card Number" }, "Value": { "type": "string", "description": "Code value.", "nullable": true, "example": "1234567890123456" } }, "additionalProperties": false }, "ClaimData": { "type": "object", "properties": { "Id": { "type": "string", "description": "Unique code identifier.", "nullable": true }, "ClaimLink": { "type": "string", "description": "Only populated for specific order / product types.", "nullable": true, "example": "https://example.com/xxxxx/yyyyyyy/zzzzzz" }, "ClaimTimestamp": { "type": "string", "description": "The date and time of claim. ISO 8601 format.", "format": "date-time", "nullable": true, "example": "2020-03-14T01:46:49Z" }, "ClaimLinkChallengeAnswer": { "type": "string", "description": "The challenge answer that the user will be prompted for upon visiting the link.\r\nPopulated only when ClaimLink is populated.", "nullable": true, "example": "ABC123" }, "BarcodePath": { "type": "string", "description": "A fully qualified url to our Barcode Service that will generate on demand.\r\nPopulated only for orders of type Codes.", "nullable": true, "example": "https://www.example.com/barcode.png" }, "BarcodeChars": { "type": "string", "description": "The characters used to generate the barcode.\r\nPopulated only for orders of type Codes.", "nullable": true }, "BarcodeType": { "$ref": "#/components/schemas/BarcodeType" }, "Codes": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimCode" }, "description": "Array of gift card codes and their associated labels.\r\nQuantity of codes in this field is dynamic to the product and its associated gift card program.\r\nMost products do not utilize more than two codes. As of this writing, no product has more than 3.\r\n \r\nFirst code can be considered the gift card code.\r\nSecond code (if present) is typically the PIN.\r\n \r\nPopulated only for orders of type Codes.", "nullable": true } }, "additionalProperties": false }, "ConflictingOrderResponse": { "type": "object", "properties": { "PONumber": { "type": "string", "description": "The PO Number common across the existing order and the requested order.", "nullable": true, "example": "PO-123456789" }, "PreviousOrderIds": { "type": "array", "items": { "type": "string" }, "description": "The order id of the original order(s). Legacy systems did not restrict uniqueness so more than one are possible.", "nullable": true } }, "additionalProperties": false }, "Department": { "required": [ "Id", "Name" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string" }, "Name": { "minLength": 1, "type": "string" } }, "additionalProperties": false }, "DepartmentBalance": { "type": "object", "properties": { "DepartmentId": { "type": "string", "nullable": true }, "Balance": { "type": "number", "format": "double" } }, "additionalProperties": false }, "DepartmentsResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Department" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "DigitalDeliveryAddress": { "type": "object", "properties": { "Sms": { "maxLength": 20, "type": "string", "description": "Recipient mobile number", "nullable": true, "example": "1234567890" }, "Email": { "maxLength": 150, "type": "string", "description": "Recipient email", "nullable": true, "example": "example@example.com" } }, "additionalProperties": false, "description": "At least one method is required." }, "InsufficientFundsResponse": { "type": "object", "properties": { "AvailableBalance": { "type": "number", "description": "Funds available for use.", "format": "double", "example": 1000 }, "OrderCost": { "type": "number", "description": "Cost of the order including any discount and fees.", "format": "double", "example": 1200 } }, "additionalProperties": false }, "LineItemPersonalization": { "required": [ "FromName", "To" ], "type": "object", "properties": { "To": { "maxLength": 150, "minLength": 1, "type": "string", "description": "First and last name of the recipient." }, "FromName": { "maxLength": 150, "minLength": 1, "type": "string", "description": "Name to display as the sender of the gift. Defaults to name of api caller." }, "FromEmail": { "maxLength": 150, "type": "string", "description": "Email to display as the sender of the gift. Defaults to email of api caller.", "nullable": true }, "Message": { "maxLength": 400, "type": "string", "description": "Message to display to the recipient of the gift.", "nullable": true }, "DeliveryDate": { "type": "string", "description": "Date and time to deliver gift (UTC). Applicable only to orders of type DigitalDelivery. Defaults to moment order is placed when not specified.", "format": "date-time", "nullable": true, "example": "2019-01-27T01:14:00Z" } }, "additionalProperties": false }, "LineItemStatus": { "enum": [ "Pending", "Completed", "Cancelled", "Sent", "Claimed", "SentToFulfillment", "Shipped" ], "type": "string" }, "OrderPersonalization": { "type": "object", "properties": { "PhotoUrl": { "maxLength": 150, "type": "string", "description": "Fully qualified URL to an image that will be featured in the personalization step of the delivery experience.", "nullable": true }, "GreetingUrl": { "maxLength": 150, "type": "string", "description": "Fully qualified URL to a greeting card that will be featured in the personalization step of the delivery experience.\r\nOptimal size is 750 x 970 pixels.", "nullable": true }, "VideoUrl": { "maxLength": 150, "type": "string", "description": "Fully qualified URL to a video that will be featured in the personalization step of the delivery experience.", "nullable": true } }, "additionalProperties": false }, "OrderRequest": { "required": [ "LineItems", "PONumber", "Type" ], "type": "object", "properties": { "Type": { "enum": [ "DigitalDelivery", "PhysicalShipment", "Links" ], "type": "string (DeliveryType)" }, "LineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderRequestLineItem" } }, "Personalization": { "$ref": "#/components/schemas/OrderPersonalization" }, "PONumber": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Identifier for the order set by the caller. Must be unique.", "example": "PO-123456789" }, "Note": { "maxLength": 250, "type": "string", "description": "Optional text pass-through.", "nullable": true, "example": "Placed for XYZ recipients" }, "DepartmentId": { "maxLength": 50, "type": "string", "description": "Id of department that will be associated with the order.\r\nNot to be provided unless configured.\r\nMUST be provided if configured.", "nullable": true, "example": "Dept123" }, "WebhookSettings": { "$ref": "#/components/schemas/OrderRequestWebhookSettings" } }, "additionalProperties": false }, "OrderRequestLineItem": { "required": [ "ProductId", "Quantity", "Value" ], "type": "object", "properties": { "ExternalId": { "maxLength": 100, "type": "string", "description": "Optional text pass-through.", "nullable": true }, "ProductId": { "minLength": 1, "type": "string", "description": "Must be one of the products available to the caller.", "example": "MGWGCPB" }, "ProductVariantId": { "type": "string", "description": "Only applicable in some workflows of specific products. Covered by secondary documentation.", "nullable": true }, "Value": { "type": "number", "description": "Must be a denomination in the range of available values for the given ProductId.", "format": "double", "example": 75 }, "Quantity": { "type": "integer", "description": "Not applicable to orders of type `DigitalDelivery`.", "format": "int32", "example": 1 }, "Culture": { "type": "string", "description": "For specifying localization aspects of delivery experiences.\r\nAcceptable values can be found in each product's `CultureCodes`.", "nullable": true, "example": "en-US" }, "BrandingId": { "type": "string", "description": "Optional field. Should not be specified unless your account has been explicitly preconfigured to support additional branding ids. Only applicable to orders of types Links, DigitalDelivery.", "nullable": true }, "PhysicalDeliveryAddress": { "$ref": "#/components/schemas/PhysicalDeliveryAddress" }, "DigitalDeliveryAddress": { "$ref": "#/components/schemas/DigitalDeliveryAddress" }, "Personalization": { "$ref": "#/components/schemas/LineItemPersonalization" }, "CardholderInformation": { "$ref": "#/components/schemas/CardholderInformation" } }, "additionalProperties": false }, "OrderRequestWebhookSettings": { "type": "object", "properties": { "FulfillmentComplete": { "maxLength": 500, "type": "string", "description": "Fully qualified url to a customer-maintained endpoint.\r\nApplicable for orders of types Codes or PhysicalDelivery.\r\nWe will post json to this endpoint upon an order being completely fulfilled.\r\nThe POST will auto-retry (exponentially backed-off) until deemed successful, be aware that you may receive a message multiple times for a given order.\r\nThe timestamp (UTC) included in the request body will be the time of the original attempt.\r\nSample request body: ```{ \"Action\": \"FulfillmentComplete\", \"OrderId\": \"BLK-123456789\", \"PONumber\": \"SomeCustomerId-123456789\", \"Timestamp\": \"06/19/2019 11:58:00 AM\" }```", "nullable": true, "example": "https://webhooks.acme.com/rewards-api?some=param" } }, "additionalProperties": false }, "OrderResponse": { "required": [ "Id", "LineItems", "PONumber", "Status", "Timestamp", "Type" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string", "description": "The unique identifier of the order." }, "Timestamp": { "type": "string", "description": "The date and time the order was created. ISO 8601 format.", "format": "date-time", "example": "2020-03-14T01:46:49Z" }, "Date": { "type": "string", "description": "The date the order was created. Will be removed in a future release.", "nullable": true, "readOnly": true, "deprecated": true }, "Status": { "$ref": "#/components/schemas/OrderStatus" }, "LineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponseLineItem" } }, "CurrencyCode": { "type": "string", "description": "ISO 4217.\r\nAll product selections within an order must match have matching currencies.", "nullable": true, "example": "USD" }, "Type": { "enum": [ "DigitalDelivery", "PhysicalShipment", "Links" ], "type": "string (DeliveryType)" }, "Personalization": { "$ref": "#/components/schemas/OrderPersonalization" }, "PONumber": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Identifier for the order set by the caller. Must be unique.", "example": "PO-123456789" }, "Note": { "maxLength": 250, "type": "string", "description": "Optional text pass-through.", "nullable": true, "example": "Placed for XYZ recipients" }, "DepartmentId": { "maxLength": 50, "type": "string", "description": "Id of department that will be associated with the order.\r\nNot to be provided unless configured.\r\nMUST be provided if configured.", "nullable": true, "example": "Dept123" }, "WebhookSettings": { "$ref": "#/components/schemas/OrderRequestWebhookSettings" } }, "additionalProperties": false }, "OrderResponseLineItem": { "required": [ "Id", "ProductId", "Quantity", "Value" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string", "description": "Unique identifier for the line item." }, "Status": { "$ref": "#/components/schemas/LineItemStatus" }, "ClaimData": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimData" }, "description": "Array of claim data This field is dynamically populated based on the requested order Type.", "nullable": true }, "Cost": { "type": "number", "description": "The cost to the client of the line item.", "format": "double", "nullable": true, "example": 71.5 }, "ExternalId": { "maxLength": 100, "type": "string", "description": "Optional text pass-through.", "nullable": true }, "ProductId": { "minLength": 1, "type": "string", "description": "Must be one of the products available to the caller.", "example": "MGWGCPB" }, "ProductVariantId": { "type": "string", "description": "Only applicable in some workflows of specific products. Covered by secondary documentation.", "nullable": true }, "Value": { "type": "number", "description": "Must be a denomination in the range of available values for the given ProductId.", "format": "double", "example": 75 }, "Quantity": { "type": "integer", "description": "Not applicable to orders of type `DigitalDelivery`.", "format": "int32", "example": 1 }, "Culture": { "type": "string", "description": "For specifying localization aspects of delivery experiences.\r\nAcceptable values can be found in each product's `CultureCodes`.", "nullable": true, "example": "en-US" }, "BrandingId": { "type": "string", "description": "Optional field. Should not be specified unless your account has been explicitly preconfigured to support additional branding ids. Only applicable to orders of types Links, DigitalDelivery.", "nullable": true }, "PhysicalDeliveryAddress": { "$ref": "#/components/schemas/PhysicalDeliveryAddress" }, "DigitalDeliveryAddress": { "$ref": "#/components/schemas/DigitalDeliveryAddress" }, "Personalization": { "$ref": "#/components/schemas/LineItemPersonalization" }, "CardholderInformation": { "$ref": "#/components/schemas/CardholderInformation" } }, "additionalProperties": false }, "OrderStatus": { "enum": [ "Pending", "Processing", "AwaitingApproval", "Completed", "Cancelled" ], "type": "string" }, "OrdersResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponse" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "PhysicalDeliveryAddress": { "required": [ "AddressLine1", "City", "Country", "Name", "ShippingMethodId", "State", "Zip" ], "type": "object", "properties": { "ShippingMethodId": { "minLength": 1, "type": "string" }, "CarrierId": { "type": "string", "description": "Optional field. Should not be specified unless your account has been explicitly preconfigured to support non-default physical carriers.", "nullable": true, "example": "PCK-123" }, "ShipmentId": { "type": "string", "description": "Optional field.\r\nUsed for signifying that multiple line items are to be shipped together.\r\nOmitting this field signifies that each line item is an individual shipment.\r\nValue does not matter, only that it matches or not across items.\r\nWhen present, all shipment items must share exact values across all shipment-related fields such as `CarrierId`, `ShippingMethodId`, and other address information.\r\nWhen mixing line items in a shipment ensure the selected `CarrierId` can support the total quantity of items requested.\r\nProducts having different fulfillment groups cannot be mixed in a single shipment.", "nullable": true, "example": "A" }, "Name": { "maxLength": 150, "minLength": 1, "type": "string", "description": "Full Name.", "example": "Recipient Name" }, "AddressLine1": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Street and number, P.O. box, c/o.", "example": "315 Main Street" }, "AddressLine2": { "maxLength": 100, "type": "string", "description": "Apartment, suite, unit, building, floor, etc.", "nullable": true, "example": "Second Floor" }, "AddressLine3": { "maxLength": 30, "type": "string", "description": "Typically used as a company name with physical fulfillment partners where supported", "nullable": true }, "City": { "maxLength": 100, "minLength": 1, "type": "string", "description": "City", "example": "Huntington" }, "State": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Two character State / Province / Region code as defined in ISO 3166-2.", "example": "NY" }, "Zip": { "maxLength": 50, "minLength": 1, "type": "string", "description": "Zip / Postal Code.", "example": "11743" }, "Country": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Two character Country / Region code as defined in ISO 3166-2.", "example": "US" } }, "additionalProperties": false }, "Product": { "required": [ "AvailableDeliveryTypes", "Denominations", "Id", "Name" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string", "description": "Product unique identifier." }, "Denominations": { "type": "array", "items": { "type": "number", "format": "double" }, "description": "In the case of `ProductDenominationType` being `Fixed`, this array contains the explicit available denominations.\r\nIn the case of `ProductDenominationType` being `Variable`, this array will contain the (inclusive) lower and upper bounds. Any cent value between is available.\r\nIn the case of `ProductDenominationType` being `VariableNoCents`, this array will contain the (inclusive) lower and upper bounds. Any whole-dollar value between is available." }, "ShortDescription": { "maxLength": 600, "type": "string", "description": "May contain HTML.", "nullable": true }, "LongDescription": { "maxLength": 4000, "type": "string", "description": "May contain HTML.", "nullable": true }, "Name": { "minLength": 1, "type": "string" }, "AvailableDeliveryTypes": { "type": "array", "items": { "enum": [ "DigitalDelivery", "PhysicalShipment", "Links" ], "type": "string (DeliveryType)" }, "description": "Specifies which delivery methods are available and enabled for your account for a given product." }, "Terms": { "type": "string", "description": "May contain HTML.", "nullable": true }, "Disclaimer": { "type": "string", "description": "May contain HTML.", "nullable": true }, "RedemptionNote": { "type": "string", "description": "Multi-use blurb of text to show in the context of this brand regarding something special about redemption.\r\nMay contain HTML.", "nullable": true }, "Type": { "$ref": "#/components/schemas/ProductType" }, "DenominationType": { "$ref": "#/components/schemas/ProductDenominationType" }, "Meta": { "$ref": "#/components/schemas/ProductMeta" }, "Media": { "$ref": "#/components/schemas/ProductMedia" }, "Cost": { "$ref": "#/components/schemas/ProductCost" }, "Translations": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCopy" }, "description": "Not applicable for all products", "nullable": true }, "CurrencyCode": { "type": "string", "description": "ISO 4217.\r\nAll product selections within an order must match have matching currencies.", "nullable": true, "example": "USD" }, "CultureCodes": { "type": "array", "items": { "type": "string" }, "description": "Culture codes consisting of language and region designations. ISO 639-1 / ISO 3166.", "nullable": true } }, "additionalProperties": false }, "ProductCopy": { "type": "object", "properties": { "CultureCode": { "type": "string", "description": "May be a language or a full culture code.", "nullable": true, "example": "fr" }, "Name": { "type": "string", "nullable": true }, "Description": { "type": "string", "description": "May contain HTML.", "nullable": true }, "TermsAndConditions": { "type": "string", "description": "May contain HTML.", "nullable": true }, "SpecialTermsAndConditions": { "type": "string", "description": "May contain HTML.", "nullable": true }, "GeneralRedemptionInstructions": { "type": "string", "description": "May contain HTML.", "nullable": true }, "OnlineRedemptionInstructions": { "type": "string", "description": "May contain HTML.", "nullable": true }, "InstoreRedemptionInstructions": { "type": "string", "description": "May contain HTML.", "nullable": true }, "PrintRedemptionInstructions": { "type": "string", "description": "May contain HTML.", "nullable": true } }, "additionalProperties": false }, "ProductCost": { "type": "object", "properties": { "Fee": { "type": "number", "description": "Fee (if applicable) per product quantity ordered.", "format": "double" }, "DiscountPercentage": { "type": "number", "description": "Discount expressed as a percentage. A value of 11 signifies that a $100.00 gift card (having no applicable fees) will cost $89.00.", "format": "double" } }, "additionalProperties": false }, "ProductDenominationType": { "enum": [ "Fixed", "Variable", "VariableNoCents" ], "type": "string" }, "ProductFaceplate": { "type": "object", "properties": { "Name": { "type": "string", "nullable": true }, "Path": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ProductMedia": { "type": "object", "properties": { "Faceplates": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFaceplate" }, "nullable": true } }, "additionalProperties": false }, "ProductMeta": { "type": "object", "properties": { "ShippingConfiguration": { "$ref": "#/components/schemas/ShippingConfiguration" } }, "additionalProperties": false }, "ProductType": { "enum": [ "Digital", "Physical" ], "type": "string" }, "ProductsResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "ShippingConfiguration": { "type": "object", "properties": { "FulfillmentGroup": { "type": "string", "description": "If specified, `FulfillmentGroup` ids must match across `ShippingMethod`, (Product)`ShippingConfiguration`, and `Carrier`.", "nullable": true }, "HasRequiredCardCarriers": { "type": "boolean", "description": "If true, this product can only be shipped with specific card carriers. See `Carrier.ProductIds`." } }, "additionalProperties": false }, "ShippingMethod": { "required": [ "Id" ], "type": "object", "properties": { "Id": { "minLength": 1, "type": "string" }, "Carrier": { "type": "string", "nullable": true }, "Description": { "type": "string", "nullable": true }, "Cost": { "type": "number", "description": "If specified, `Tiers` will take precedence in determining shipment costs.", "format": "double", "nullable": true }, "Type": { "$ref": "#/components/schemas/ShippingType" }, "FulfillmentGroup": { "type": "string", "description": "If specified, `FulfillmentGroup` ids must match across `ShippingMethod`, (Product)`ShippingConfiguration`, and `Carrier`.", "nullable": true }, "Tiers": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingTier" }, "description": "If specified, the cost for the shipment can be derived by finding the appropriate tier for your order.", "nullable": true } }, "additionalProperties": false }, "ShippingMethodsResponse": { "required": [ "Data" ], "type": "object", "properties": { "Data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "Page": { "type": "integer", "description": "The one-based page index.", "format": "int32", "example": 1 }, "PageSize": { "type": "integer", "description": "Quantity of records per page of data.", "format": "int32", "example": 10 }, "TotalCount": { "type": "integer", "description": "The quantity of records across the pages in the resultset.", "format": "int32", "example": 53 } }, "additionalProperties": false }, "ShippingTier": { "type": "object", "properties": { "From": { "type": "number", "description": "If `Type` is `Quantity` this will be the lower bound of the quantity range in determining cost.\r\nIf `Type` is `Value` this will be the lower bound of the order value range in determining cost.", "format": "double" }, "To": { "type": "number", "description": "If `Type` is `Quantity` this will be the upper bound of the quantity range in determining cost.\r\nIf `Type` is `Value` this will be the upper bound of the order value range in determining cost.", "format": "double" }, "Cost": { "type": "number", "format": "double" }, "Type": { "$ref": "#/components/schemas/ShippingTierType" } }, "additionalProperties": false }, "ShippingTierType": { "enum": [ "Quantity", "Value" ], "type": "string" }, "ShippingType": { "enum": [ "DirectDelivery", "Bulk" ], "type": "string" }, "Token": { "required": [ "Value" ], "type": "object", "properties": { "Value": { "minLength": 1, "type": "string" }, "ExpiresIn": { "type": "integer", "description": "Time until expiration in minutes.", "format": "int32" } }, "additionalProperties": false }, "ValidationError": { "required": [ "Errors", "Property" ], "type": "object", "properties": { "Property": { "minLength": 1, "type": "string", "description": "Path of the request property that triggered a validation error." }, "Errors": { "type": "array", "items": { "type": "string" }, "description": "Issues with the specified request property." } }, "additionalProperties": false }, "ValidationErrorResponse": { "required": [ "Errors" ], "type": "object", "properties": { "Errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" }, "description": "Array of validation errors." } }, "additionalProperties": false } }, "securitySchemes": { "Email": { "type": "apiKey", "description": "The email address for a given account for which API access has been enabled.", "name": "Email", "in": "header" }, "AccessToken": { "type": "apiKey", "description": "The access token that was provisioned for the user specified in the Email header", "name": "AccessToken", "in": "header" }, "Bearer": { "type": "apiKey", "description": "Authorization header using the Bearer scheme. Example: `Authorization: Bearer {token}`. See Tokens section for Bearer token generation.", "name": "Authorization", "in": "header" } } } }