Imprint Public API

openapi: 3.1.0
info:
  title: Public Imprint API
  version: '2.0'
security:
  - basicAuth: []
  - bearerAuth: []
servers:
  - url: https://dev.sbx.imprint.co
    description: Imprint public api sandbox
paths:
  /v2/customers:
    get:
      tags:
        - Customers
      summary: Search for customers
      operationId: searchCustomers
      parameters:
        - name: partner_customer_id
          in: query
          description: The unique identifier for the customer in the partner's system
          schema:
            type: string
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
    post:
      tags:
        - Customers
      summary: Search for customers
      operationId: searchCustomersPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                partner_customer_id:
                  description: >-
                    The unique identifier for the customer in the partner's
                    system
                  type: string
                ssn:
                  description: The ssn of the customer without hyphens
                  example: '123456789'
                  type: string
                date_of_birth:
                  $ref: '#/components/schemas/DateOfBirth'
                limit:
                  description: Limits the number of returned results
                  type: integer
                  minimum: 1
                  default: 10
                  format: int32
                starting_after:
                  description: >-
                    A cursor for use in pagination. An id that defines your
                    place in the list.
                  type: string
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerListResponse'
  /v2/customers/{customer_id}:
    get:
      tags:
        - Customers
      summary: Retrieve a customer
      description: Retrieves the details of an existing customer by ID
      operationId: getCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier for the customer
          schema:
            type: string
            example: BBB815E9-F654-438D-9AD3-3F7BB8136FC0
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
  /v2/customers/{customer_id}/link:
    post:
      tags:
        - Customer Links
      summary: Link an Imprint customer and partner customer accounts
      description: >-
        Creates a link between an existing Imprint customer and a partner's
        customer account. The API key provided with the request will be used to
        link the partner with the imprint customer.
      operationId: linkCustomerAccount
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier for the Imprint customer
          schema:
            type: string
            example: BBB815E9-F654-438D-9AD3-3F7BB8136FC0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - partner_customer_id
              properties:
                partner_customer_id:
                  $ref: '#/components/schemas/PartnerCustomerId'
                metadata:
                  type: object
                  description: Additional linking metadata
                  additionalProperties: true
                  example:
                    store_id: store_789
                    platform_version: 2.1.0
      responses:
        '200':
          description: Customer accounts linked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerLink'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
        '409':
          description: Customer already linked
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                    properties:
                      type:
                        type: string
                        description: Error type (e.g., CUSTOMER_ALREADY_LINKED)
                      message:
                        type: string
                        example: Customer already linked to a partner account
                      existing_link:
                        $ref: '#/components/schemas/CustomerLink'
  /v2/customer_sessions:
    post:
      tags:
        - Customer Sessions
      summary: Create a new customer session
      description: >-
        Creates a new session for a customer with a client_secret that can be
        passed to the SDK, providing client access to modify their own profile,
        card, or card/loan application. If required, a new customer will be
        created to attach this session to. Customer history can be attached to
        this session and will be included in the customer's profile if created,
        or attached to the application the customer creates during the session
      operationId: createSession
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  description: >-
                    Unique identifier for the Imprint customer, if creating a
                    customer session for a known imprint customer that the id is
                    available for
                  example: AD87A18A-A4BE-49FF-BC46-BF6F0779DBAA
                partner_customer_id:
                  type: string
                  description: >-
                    The unique identifier for the customer in the partner's
                    system
                  example: CUST_03476998
                transaction_amount:
                  type: integer
                  description: >-
                    The current transaction amount, if the session is currently
                    executing a transaction. integer value in the min currency
                    unit (cents for USD)
                  example: 34000
                transaction_currency:
                  type: string
                  description: The 3 char currency code of the amount in iso-4217
                  example: USD
                customer_history:
                  $ref: '#/components/schemas/CustomerAccountHistory'
                source:
                  type: string
                  description: The source where the session is initiated
                metadata:
                  type: object
                  description: Additional linking metadata
                  additionalProperties: true
                  example:
                    store_number: '123'
                customer_metadata:
                  type: object
                  description: >-
                    A set of key-value pairs attached to the customer. These
                    values will be included in webhook event payloads for the
                    partner to receive information about the customer.
                  additionalProperties:
                    type: string
                  example:
                    loyalty_id: '840012345678'
                    membership_tier: gold
      responses:
        '201':
          description: Customer session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSession'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  /v2/customer_sessions/{session_id}:
    get:
      tags:
        - Customer Sessions
      summary: Retrieve a session
      operationId: getSession
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Customer session retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSession'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionNotFoundError'
  /v2/payment_methods:
    get:
      tags:
        - Payment Methods
      summary: List payment methods
      operationId: searchPaymentMethods
      parameters:
        - name: customer_id
          in: query
          required: true
          description: The unique identifier for the customer
          schema:
            type: string
            example: DE92AF9E-E705-4B8E-9184-6D976DBD8050
        - name: type
          in: query
          description: The type of payment method to filter by
          schema:
            type: string
            enum:
              - LOAN
              - CARD
              - BANK_ACCOUNT
            example: LOAN
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of customer payment methods
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
                  has_more:
                    type: boolean
                  total:
                    type: integer
    post:
      tags:
        - Payment Methods
      summary: List payment methods
      operationId: searchPaymentMethodsPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  description: The Imprint customer id
                  example: 54CFF41D-0AA0-4D16-853B-608C5AAF503D
                type:
                  type: string
                  description: The type of payment method to filter by
                  enum:
                    - LOAN
                    - CARD
                    - BANK_ACCOUNT
                  example: CARD
                pan:
                  type: string
                  description: The card pan to search by
                  example: '4111111592341815'
      responses:
        '200':
          description: List of customer payment methods
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
                  has_more:
                    type: boolean
                  total:
                    type: integer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  /v2/payment_methods/{payment_method_id}:
    get:
      tags:
        - Payment Methods
      summary: Retrieve a payment method
      description: >-
        Retrieves the details of the payment method associated with the supplied
        `payment_method_id`
      operationId: getPaymentMethod
      parameters:
        - name: payment_method_id
          in: path
          required: true
          description: The unique identifier of the payment method
          schema:
            type: string
            example: 9ED4FE47-8E9C-48E9-BBEF-094DF1789012
      responses:
        '200':
          description: Payment method retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '404':
          description: Payment method not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodNotFoundError'
  /v2/transaction_intents:
    post:
      tags:
        - Transaction Intents
      summary: Create a transaction intent
      description: >-
        Creates a transaction intent object that represents a pending financial
        transaction. Transaction intents are used to initiate, validate, and
        track the lifecycle of a transaction before it is finalized.
      operationId: createTransactionIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
                - amount
                - currency
              properties:
                customer_id:
                  type: string
                  description: >-
                    The Imprint Customer ID of the customer making the
                    transaction intent
                  example: F9B5A5E8-C8B0-4B7A-8E6B-0C8EE90A62CF
                payment_method_id:
                  type: string
                amount:
                  type: integer
                  description: Amount in min units.
                  example: 10000
                currency:
                  $ref: '#/components/schemas/TransactionCurrency'
                network_transaction_id:
                  type: string
                  description: >-
                    The network's unique identifier for the transaction.
                    Examples include Visa Transaction ID, Mastercard Trace ID,
                    and American Express Network Reference ID
                merchant_name:
                  type: string
                  description: The name of the merchant this transaction intent will be
                  example: walmart
                merchant_address:
                  $ref: '#/components/schemas/Address'
                merchant_id:
                  type: string
                merchant_code:
                  type: string
                expected_date:
                  type: string
                  description: >-
                    the RFC-3339 date when the transaction is expected to
                    process. This does not have to be exact but it will be used
                    as a data point to help link a transaction with a
                    transaction intent. This example includes date and time to
                    be explict, any RFC3339 date or date+time will be accepted
                  example: 2025-02-13T19:08:07.000Z
                metadata:
                  type: object
                  additionalProperties: true
                  example:
                    platform_version: 2.1.0
      responses:
        '200':
          description: Transaction intent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionIntent'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
    get:
      tags:
        - Transaction Intents
      summary: List transaction intents
      description: Retrieves a list of transaction intents.
      operationId: searchTransactionIntents
      parameters:
        - name: type
          in: query
          description: The type of transaction intent to filter by.
          schema:
            type: string
            enum:
              - CONFIRMED
              - CANCELED
            example: CONFIRMED
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of transaction intents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionIntent'
                  has_more:
                    type: boolean
                  total:
                    type: integer
  /v2/transaction_intents/{intent_id}:
    get:
      tags:
        - Transaction Intents
      summary: Retrieve a transaction intent
      description: Retrieves the details of an existing transaction intent by `id`.
      operationId: getTransactionIntent
      parameters:
        - name: intent_id
          in: path
          required: true
          description: The unique identifier for the transaction intent.
          schema:
            type: string
            example: 3E4F0CCD-ACBF-42F3-A459-6DF92AF632D1
      responses:
        '200':
          description: Transaction intent retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionIntent'
        '404':
          description: Transaction intent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionIntentFoundError'
    post:
      tags:
        - Transaction Intents
      summary: Update a transaction intent
      description: >-
        Updates the details of the transaction intent associated with the
        supplied intent_id
      operationId: updateTransactionIntent
      parameters:
        - name: intent_id
          in: path
          required: true
          description: The unique identifier for the transaction intent
          schema:
            type: string
            example: 3E4F0CCD-ACBF-42F3-A459-6DF92AF632D1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
                - amount
                - status
                - created_at
              properties:
                customer_id:
                  type: string
                  example: D8CD2346-9A02-4ABB-A388-AB3DACC57DCF
                amount:
                  type: integer
                  example: 100
                status:
                  $ref: '#/components/schemas/TransactionIntentStatus'
                currency:
                  $ref: '#/components/schemas/TransactionCurrency'
                network_transaction_id:
                  type: string
                  description: >-
                    The network's unique identifier for the transaction.
                    Examples include Visa Transaction ID, Mastercard Trace ID,
                    and American Express Network Reference ID
                partner_transaction_id:
                  type: string
                  description: The partner's unique transaction id
                metadata:
                  type: object
                  description: Additional transaction intent data
                  additionalProperties: true
                  example:
                    platform_version: 2.1.0
      responses:
        '200':
          description: Transaction intent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionIntent'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  /v2/transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      summary: Retrieve a transaction
      description: Retrieves the details of an existing transaction by `id`
      operationId: getTransaction
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: The unique identifier for the transaction
          schema:
            type: string
            example: 4E6FE207-53E5-4EC0-BF51-5923BE5CEE2F
      responses:
        '200':
          description: Transaction retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionNotFoundError'
  /v2/rewards:
    get:
      tags:
        - Rewards
      summary: Search for rewards
      operationId: searchRewards
      parameters:
        - name: transaction_event_id
          in: query
          description: Reward associated to the transaction event
          schema:
            type: string
            example: 40fa8333-f809-4861-9839-45f41d50077d
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reward'
                  has_more:
                    type: boolean
                  total:
                    type: integer
  /v2/rewards/{reward_id}:
    get:
      tags:
        - Rewards
      summary: Retrieve a reward
      description: Retrieves the details of an existing reward by ID
      operationId: getReward
      parameters:
        - name: reward_id
          in: path
          required: true
          description: The unique identifier for the reward
          schema:
            type: string
            example: B552A4A1-9B31-4414-8AEE-E735A8652EDA
      responses:
        '200':
          description: Reward retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '404':
          description: Reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardNotFoundError'
    patch:
      tags:
        - Rewards
      summary: Updates a reward
      description: Updates the status or amount of pending rewards
      operationId: patchReward
      parameters:
        - name: reward_id
          in: path
          required: true
          schema:
            type: string
            example: 2EE24580-B97B-4949-A65C-929CCB9B9B8D
          description: Unique identifier for the reward
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: amount to update the reward
                  example: 120000
                status:
                  $ref: '#/components/schemas/RewardStatus'
      responses:
        '200':
          description: Reward updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
  /v2/customers/{customer_id}/rewards_balance:
    get:
      tags:
        - Customers
      summary: Get customer's current rewards balance
      operationId: getRewardsBalance
      parameters:
        - name: customer_id
          $ref: '#/components/parameters/customerIdParam'
      responses:
        '200':
          description: Customer rewards balance
          content:
            application/json:
              schema:
                type: object
                required:
                  - customer_id
                  - reward_balance
                  - reward_symbol
                properties:
                  customer_id:
                    type: string
                    description: The unique identifier for the customer
                    example: 2EE24580-B97B-4949-A65C-929CCB9B9B8D
                  reward_balance:
                    type: integer
                    description: The integer value of the customer's rewards balance
                    example: 120000
                  reward_symbol:
                    type: string
                    description: >-
                      The symbol for the rewards. Can be in currency like `$` or
                      things like `points`
                  reward_description:
                    type: string
                    description: >-
                      The description of the rewards, can be displayed to the
                      customer
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
  /v2/customers/{customer_id}/payment_methods:
    get:
      tags:
        - Customers
      summary: List customer's payment methods
      operationId: getPaymentMethods
      parameters:
        - name: customer_id
          $ref: '#/components/parameters/customerIdParam'
      responses:
        '200':
          description: Customer rewards balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
  /v2/customers/{customer_id}/transaction_intents:
    get:
      tags:
        - Customers
      summary: List customer's transaction intents
      operationId: getTransactionIntents
      parameters:
        - name: customer_id
          in: path
          $ref: '#/components/parameters/customerIdParam'
      responses:
        '200':
          description: Customer transaction intents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionIntent'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionNotFoundError'
  /v2/customers/{customer_id}/transactions:
    get:
      tags:
        - Customers
      summary: List customer's transactions
      operationId: getTransactions
      parameters:
        - name: customer_id
          $ref: '#/components/parameters/customerIdParam'
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of customer transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  has_more:
                    type: boolean
                  total:
                    type: integer
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
  /v2/customers/{customer_id}/rewards:
    get:
      tags:
        - Customers
      summary: List customer's rewards
      description: >-
        List customer's rewards in descending order by the reward's updated at
        timestamp
      operationId: getRewards
      parameters:
        - name: customer_id
          $ref: '#/components/parameters/customerIdParam'
        - name: limit
          $ref: '#/components/parameters/limitParam'
        - name: starting_after
          $ref: '#/components/parameters/startingAfterParam'
      responses:
        '200':
          description: List of customer rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reward'
                  has_more:
                    type: boolean
                  total:
                    type: integer
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerNotFoundError'
  /v2/offers:
    get:
      tags:
        - Offers
      summary: Retrieve an offer
      x-excluded: true
      operationId: getOffer
      description: Returns the marketing placement for the given customer
      parameters:
        - name: partner_customer_id
          in: query
          schema:
            type: string
            description: The unique identifier for the customer in the partner's system
      responses:
        '200':
          description: Successfully returned marketing placement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offer'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCustomerNotFoundError'
  /v2/order_events:
    get:
      tags:
        - Order Events
      summary: Retrieve order events
      description: Get a list of order events
      operationId: listOrderEvents
      parameters:
        - name: order_event_id
          in: query
          description: >-
            An order event ID. If provided, the response will only have a
            maximum of one result.
          schema:
            type: string
          example: 7622c07d-eb2b-4345-a9a9-345d61d32bc2
        - name: order_id
          in: query
          description: Enables searching for events by order ID
          schema:
            type: string
          example: 77f60af4-185e-4867-b113-34e3cf7c6acd
        - name: partner_event_id
          in: query
          description: >-
            The identifier of the order event in the partner system. If
            provided, the response will only have a maximum of one result.
          schema:
            type: string
        - name: network_transaction_id
          description: >-
            The network's unique identifier for the transaction. Examples
            include Visa Transaction ID, Mastercard Trace ID, and American
            Express Network Reference ID
          in: query
         

# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/imprint/refs/heads/main/openapi/imprint-openapi-original.yml