BigCommerce
Theme & Content APIs
Gift Certificates

Marketing

Get a Gift Certificate

GET /gift_certificates/{id}

Request

Returns a single Gift Certificate.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • id in path - integer - required

    ID of the gift certificate.

example

Response

Body

application/json
  • to_name
    string
    required

    Name of the recipient.

    Example: John Doe

  • to_email
    string
    required

    Email of the recipient.

    Example: johndoe@example.com

  • from_name
    string
    required

    Name of the customer who purchased the gift certificate.

    Example: Jane Doe

  • from_email
    string
    required

    Email of the customer who purchased the gift certificate.

    Example: janedoe@example.com

  • amount
    string
    required

    Value of the gift certificate.

    Example: 10

  • id
    integer

    The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

    Example: 1

  • customer_id
    integer

    The ID of the customer placing the order.

    Example: 5

  • order_id
    integer

    The ID of the order.

    Example: 116

  • balance
    string

    Remaining value of the gift certificate. If not set, will default to the amount.

    Example: 0

  • purchase_date
    string

    Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.

    Example: Tue, 20 Jan 1970 08:45:38 CST

  • expiry_date
    string

    Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.

    Example: Mon, 2 Jan 2023 08:45:38 CST

  • template
    string

    The email theme to use in the message sent to the recipient.

    Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message
    string

    Text that will be sent to the recipient, such as “Congratulations.”

    Example: Congratulations!

  • code
    string

    A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

    <= 255 characters

    Example: FFZ-5N4-C7M-S78

  • status
    string

    Allowed: active | pending | disabled | expired

    Example: active

  • currency_code
    string

    A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

    Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

    Example: USD

    example

    Update a Gift Certificate

    PUT /gift_certificates/{id}

    Request

    Updates a Gift Certificate.

    Read Only Fields

    • id
    • order_id

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • id in path - integer - required

      ID of the gift certificate.

    • Content-Type in header with default of application/json - string - required

      The MIME type of the request body.

    Body

    application/json
    • to_name
      string
      required

      Name of the recipient.

      Example: John Doe

    • to_email
      string
      required

      Email of the recipient.

      Example: johndoe@example.com

    • from_name
      string
      required

      Name of the customer who purchased the gift certificate.

      Example: Jane Doe

    • from_email
      string
      required

      Email of the customer who purchased the gift certificate.

      Example: janedoe@example.com

    • amount
      string
      required

      Value of the gift certificate.

      Example: 10

    • balance
      string

      The remaining value of the gift certificate. If not set, will default to the amount.

      Example: 0

    • purchase_date
      string

      Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Enter date in RFC-2822 format.

      Example: Mon, 19 Jan 1970 07:21:46 CST

    • expiry_date
      string

      Date on which the gift certificate is set to expire.

      Example: Mon, 02 Jan 2023 08:45:38 CST

    • customer_id
      integer

      The ID of the customer placing the order.

      Example: 5

    • template
      string

      The email theme to use in the message sent to the recipient.

      Allowed: birthday.html | boy.html | girl.html | celebration.html | christmas.html | general.html

      Example: celebration.html

    • message
      string

      Text that will be sent to the recipient, such as “Congratulations.”

      Example: Congratulations!

    • code
      string

      A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

      <= 255 characters

      Example: FFZ-5N4-C7M-S78

    • status
      string

      Allowed: active | pending | expired | disabled

      Example: active

    • currency_code
      string

      A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

      Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

      Example: USD

      example

      Response

      Body

      application/json
      • to_name
        string
        required

        Name of the recipient.

        Example: John Doe

      • to_email
        string
        required

        Email of the recipient.

        Example: johndoe@example.com

      • from_name
        string
        required

        Name of the customer who purchased the gift certificate.

        Example: Jane Doe

      • from_email
        string
        required

        Email of the customer who purchased the gift certificate.

        Example: janedoe@example.com

      • amount
        string
        required

        Value of the gift certificate.

        Example: 10

      • id
        integer

        The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

        Example: 1

      • customer_id
        integer

        The ID of the customer placing the order.

        Example: 5

      • order_id
        integer

        The ID of the order.

        Example: 116

      • balance
        string

        Remaining value of the gift certificate. If not set, will default to the amount.

        Example: 0

      • purchase_date
        string

        Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.

        Example: Tue, 20 Jan 1970 08:45:38 CST

      • expiry_date
        string

        Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.

        Example: Mon, 2 Jan 2023 08:45:38 CST

      • template
        string

        The email theme to use in the message sent to the recipient.

        Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

        Example: celebration.html

      • message
        string

        Text that will be sent to the recipient, such as “Congratulations.”

        Example: Congratulations!

      • code
        string

        A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

        <= 255 characters

        Example: FFZ-5N4-C7M-S78

      • status
        string

        Allowed: active | pending | disabled | expired

        Example: active

      • currency_code
        string

        A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

        Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

        Example: USD

        example

        Delete a Gift Certificate

        DELETE /gift_certificates/{id}

        Request

        Deletes a Gift Certificate.

        Authentication

        • X-Auth-Token in header - required

        Parameters

        • store_hash in path - string
        • Accept in header with default of application/json - string - required

          The MIME type of the response body.

        • id in path - integer - required

          ID of the gift certificate.

        example

        Response

        Get All Gift Certificates

        GET /gift_certificates

        Request

        Returns a list of Gift Certificates. Optional filter parameters can be passed in.

        Default sorting is by gift-certificate id, from lowest to highest.

        The maximum limit is 250. If a limit isn’t provided, up to 50 gift_certificates are returned by default.

        Authentication

        • X-Auth-Token in header - required

        Parameters

        • store_hash in path - string
        • Accept in header with default of application/json - string - required

          The MIME type of the response body.

        • min_id in query - integer
        • max_id in query - integer
        • code in query - string
        • order_id in query - integer
        • to_name in query - string
        • to_email in query - string
        • from_name in query - string
        • from_email in query - string
        • page in query - number
        • limit in query - number

        example

        Response

        Body

        array | application/json

          example

          Create a Gift Certificate

          POST /gift_certificates

          Request

          Creates a Gift Certificate.

          Required Fields

          • to_name
          • to_email
          • from_name
          • from_email
          • amount

          Read Only Fields

          • id
          • order_id

          Notes

          When a gift certificate is created through the API, no email notification is triggered to the specified recipient.

          Authentication

          • X-Auth-Token in header - required

          Parameters

          • store_hash in path - string
          • Content-Type in header with default of application/json - string - required

            The MIME type of the request body.

          Body

          application/json
          • to_name
            string
            required

            Name of the recipient.

            Example: John Doe

          • to_email
            string
            required

            Email of the recipient.

            Example: johndoe@example.com

          • from_name
            string
            required

            Name of the customer who purchased the gift certificate.

            Example: Jane Doe

          • from_email
            string
            required

            Email of the customer who purchased the gift certificate.

            Example: janedoe@example.com

          • amount
            string
            required

            Value of the gift certificate.

            Example: 10

          • balance
            string

            Remaining value of the gift certificate. If not set, will default to the amount.

            Example: 0

          • purchase_date
            string

            Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Enter date in RFC-2822 format.

            Example: Mon, 19 Jan 1970 07:21:46 CST

          • expiry_date
            string

            Date on which the gift certificate is set to expire. The date must be in RFC 2822 format.

            Example: Tue, 20 Jan 1970 08:45:38 CST

          • customer_id
            integer

            The ID of the customer placing the order.

            Example: 5

          • template
            string

            The email theme to use in the message sent to the recipient.

            Allowed: birthday.html | boy.html | girl.html | celebration.html | christmas.html | general.html

            Example: celebration.html

          • message
            string

            Text that will be sent to the recipient, such as “Congratulations.”

            <= 250 characters

            Example: Congratulations!

          • code
            string

            A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

            <= 255 characters

            Example: FFZ-5N4-C7M-S78

          • status
            string

            Allowed: active | pending | expired | disabled

            Example: active

          • currency_code
            string

            A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

            Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

            Example: USD

            example

            Response

            Body

            application/json
            • to_name
              string
              required

              Name of the recipient.

              Example: John Doe

            • to_email
              string
              required

              Email of the recipient.

              Example: johndoe@example.com

            • from_name
              string
              required

              Name of the customer who purchased the gift certificate.

              Example: Jane Doe

            • from_email
              string
              required

              Email of the customer who purchased the gift certificate.

              Example: janedoe@example.com

            • amount
              string
              required

              Value of the gift certificate.

              Example: 10

            • id
              integer

              The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

              Example: 1

            • customer_id
              integer

              The ID of the customer placing the order.

              Example: 5

            • order_id
              integer

              The ID of the order.

              Example: 116

            • balance
              string

              Remaining value of the gift certificate. If not set, will default to the amount.

              Example: 0

            • purchase_date
              string

              Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.

              Example: Tue, 20 Jan 1970 08:45:38 CST

            • expiry_date
              string

              Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.

              Example: Mon, 2 Jan 2023 08:45:38 CST

            • template
              string

              The email theme to use in the message sent to the recipient.

              Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

              Example: celebration.html

            • message
              string

              Text that will be sent to the recipient, such as “Congratulations.”

              Example: Congratulations!

            • code
              string

              A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

              <= 255 characters

              Example: FFZ-5N4-C7M-S78

            • status
              string

              Allowed: active | pending | disabled | expired

              Example: active

            • currency_code
              string

              A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

              Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

              Example: USD

              example

              Delete All Gift Certificates

              DELETE /gift_certificates

              Request

              By default, it deletes all Gift Certificates.

              Authentication

              • X-Auth-Token in header - required

              Parameters

              • store_hash in path - string
              • Accept in header with default of application/json - string - required

                The MIME type of the response body.

              example

              Response

              Body

              object | application/json

                example

                Did you find what you were looking for?