OpenAPI Specification
openapi: 3.0.3
info:
title: Giftbit Brands Campaigns API
description: 'Giftbit''s REST API allows you to automatically order rewards and send them to your recipients. Delivery can be handled either by links integrated into another system''s workflow or by emails sent through the Giftbit system. The API supports email delivery, shortlinks, direct links, and in-app embedded reward flows across 1,500+ brands in 40+ countries.
'
version: 1.0.0
contact:
email: sales@giftbit.com
termsOfService: https://www.giftbit.com
servers:
- url: https://api.giftbit.com/papi/v1
description: Production API
- url: https://api-testbed.giftbit.com/papi/v1
description: Testbed (Sandbox) API
security:
- BearerAuth: []
tags:
- name: Campaigns
description: Create and manage email reward orders
paths:
/campaign:
post:
operationId: createEmailOrder
summary: Create email order
description: 'Places an order for one or more emailed rewards. Supports single-brand and full-catalog (multi-brand) reward offers. A client-supplied `id` makes this operation idempotent — resend safely on unexpected errors.
'
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailOrderRequest'
example:
gift_template: XDKHE
contacts:
- firstname: Perry
lastname: Johnson
email: pjohnson@giftbit.com
price_in_cents: 2500
brand_codes:
- itunesus
- amazonus
id: order-abc123
responses:
'200':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/campaign/{id}:
get:
operationId: retrieveOrderById
summary: Retrieve order by ID
description: Retrieves status and information about a specified reward order.
tags:
- Campaigns
parameters:
- name: id
in: path
required: true
description: The client-supplied identifier for the order.
schema:
type: string
responses:
'200':
description: Order details
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
ErrorDetail:
type: object
properties:
code:
type: string
description: Enum-style error code.
name:
type: string
description: Human-readable error name.
message:
type: string
description: Context-specific error message.
ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
status:
type: integer
description: HTTP status code.
Fees:
type: object
properties:
cost_entries:
type: array
items:
$ref: '#/components/schemas/FeeEntry'
subtotal_in_cents:
type: integer
tax_in_cents:
type: integer
tax_type:
type: string
total_in_cents:
type: integer
CampaignResponse:
type: object
properties:
info:
$ref: '#/components/schemas/InfoBlock'
campaign:
$ref: '#/components/schemas/Campaign'
status:
type: integer
Campaign:
type: object
properties:
uuid:
type: string
description: Giftbit-generated unique order identifier.
id:
type: string
description: Client-supplied order identifier.
price_in_cents:
type: integer
description: Reward value in cents.
brand_code:
type: string
description: Brand code (single-brand orders).
brand_codes:
type: array
items:
type: string
description: Brand codes (multi-brand orders).
fees:
$ref: '#/components/schemas/Fees'
Contact:
type: object
required:
- email
properties:
email:
type: string
format: email
description: Recipient email address.
example: pjohnson@giftbit.com
firstname:
type: string
description: Recipient first name.
example: Perry
lastname:
type: string
description: Recipient last name.
example: Johnson
CreateEmailOrderRequest:
type: object
required:
- contacts
- price_in_cents
- id
properties:
message:
type: string
description: Reward email message. Required if no template is supplied.
subject:
type: string
description: Reward email subject. Required if no template is supplied.
gift_template:
type: string
description: Template id from the web account templates section.
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
description: List of recipients.
price_in_cents:
type: integer
description: Reward value in cents (e.g. 2500 = $25.00).
brand_codes:
type: array
items:
type: string
description: List of brand codes to limit choice. Not for full-catalog.
region:
type: string
description: Geographic region for full-catalog rewards.
expiry:
type: string
format: date
description: Claim-before date (YYYY-MM-dd). Max one year from creation.
id:
type: string
description: Client-supplied unique order identifier for idempotent requests.
FeeEntry:
type: object
properties:
percentage:
type: number
description: Fee as a percentage.
fee_type:
type: string
description: Type of fee (e.g. PREFUND_GIFT_COST, UPFRONT_PER_GIFT_FEE).
amount_in_cents:
type: integer
description: Total fee amount in cents.
currency:
type: string
description: Currency code.
tax_type:
type: string
description: Tax type (e.g. NOTAX).
tax_in_cents:
type: integer
description: Tax amount in cents.
number_of_gifts:
type: integer
description: Number of gifts this fee applies to.
fee_per_gift_in_cents:
type: integer
description: Per-gift fee in cents.
InfoBlock:
type: object
properties:
code:
type: string
description: Status code (e.g. INFO_CAMPAIGN_CREATED).
name:
type: string
description: Human-readable status name.
message:
type: string
description: Context-specific status message.
responses:
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
UnprocessableEntity:
description: The request was valid but could not be processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Authentication failed — invalid or missing bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Authenticate by sending your API token prefixed with "Bearer " in the Authorization HTTP header. Generate tokens from your Giftbit account under Account -> API keys.
'