Create voucher order

POST https://www.digicert.com/services/v2/voucher

Use this endpoint to place a voucher order. To order voucher codes for multiple products at once, pass a voucher object for each product configuration you want to order.

Note

Each voucher order is intended to be used by the same customer. If you need to order vouchers for multiple customers, place separate orders for each customer.

Example requests and responses

Example 1. cURL

curl --request POST 'https://www.digicert.com/services/v2/voucher' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "vouchers": [
    {
      "product_name_id": "ssl_ev_basic",
      "no_of_fqdns": 5,
      "validity_years": 1,
      "quantity": 1,
      "use_san_package": true
    },
    {
      "product_name_id": "ssl_ev_securesite_pro",
      "no_of_fqdns": 2,
      "validity_years": 2,
      "quantity": 1
    }
  ],
  "payment_method": "balance"
}'

Example 2. 201 Created

{
  "id": 25261,
  "name": "Example",
  "status": "completed",
  "cost": 10039.9,
  "cost_plus_tax": 10039.9,
  "created_date": "2022-03-03 15:38:43",
  "expiration_date": "2023-03-03",
  "receipt_id": 200896,
  "codes": [
    {
      "id": 2104,
      "value": "QWWQ7LQSO72QLPXEXMC5OA65SHS2CPWJ",
      "product": {
        "name_id": "ssl_ev_basic"
      },
      "no_of_fqdns": 5,
      "validity_years": 1,
      "status": "active"
    },
    {
      "id": 2105,
      "value": "WWXPP6EC2GUXRYY4AE52FMOZ33K32M7K",
      "product": {
        "name_id": "ssl_ev_securesite_pro"
      },
      "no_of_fqdns": 2,
      "validity_years": 2,
      "status": "active"
    }
  ],
{
    "id": 1014,
    "name": "My test voucher order",
    "status": "completed",
    "cost": 2698,
    "expiration_date": "2021-07-09",
    "codes": [
        {
            "id": 2104,
            "value": "QWWQ7LQSO72QLPXEXMC5OA65SHS2CPWJ",
            "product": {
                "name_id": "ssl_ev_basic"
            },
            "no_of_fqdns": 5,
            "validity_years": 1,
            "status": "active"
        },
        {
            "id": 2105,
            "value": "WWXPP6EC2GUXRYY4AE52FMOZ33K32M7K",
            "product": {
                "name_id": "ssl_ev_securesite_pro"
            },
            "no_of_fqdns": 2,
            "validity_years": 2,
            "status": "active"
        }
    ],
}

Request parameters

Name	Req/Opt	Type	Description
vouchers	required	array	List of object containers for new vouchers to order.
.. product_name_id	required	string	Product name identifier. See Glossary – Product identifiers.
.. no_of_fqdns	optional	integer	Number of FQDN SAN slots. Range: `0`-`250`. Note that the total number of SANs cannot exceed 250.
.. no_of_wildcards	optional	integer	Number of Wildcard SAN slots. Range: `0`-`250`. Note that the total number of SANs cannot exceed 250.
.. validity_years	conditional	integer	The number of years of order coverage. You must provide a value for either `validity_years` or `validity_days`. Range: Maximum order validity varies by product. To get the maximum order validity period for a product, use the Product info endpoint.
.. validity_days	conditional	integer	The number of days of order coverage. Overrides `validity_years`. You must provide a value for either `validity_years` or `validity_days`. Range: Maximum order validity varies by product. To get the maximum order validity period for a product, use the Product info endpoint.
.. quantity	required	integer	Quantity of certificates you want to order with this configuration. Each certificate receives a unique voucher code. Range: `1`-`1000`
.. shipping_method	conditional	string	For document signing and code signing certificates, choose how the requestor will provision or ship the certificates. Usage requirements depend on product type. Document signing certificates:`shipping_method` is required. Allowed values are `STANDARD` and `EXPEDITED`. Note Regardless of the shipping method, the requestor redeeming the voucher can choose a provisioning method of either Preconfigured Hardware Token (`ship_token`) or Use Existing Token (`client_app`). If they choose Preconfigured Hardware Token, they must use the same shipping method included on the voucher. Code signing certificates:`shipping_method` is optional. Allowed values are `STANDARD`, `EXPEDITED`, and `KEYLOCKER`. The presence or absence of the `shipping_method` field determines which provisioning methods the requestor can use when redeeming the voucher. `shipping_method` is `STANDARD` or `EXPEDITED`: Creates a voucher that allows the requestor to choose a provisioning method of DigiCert-provided hardware token (`ship_token`). Voucher cost includes price of both certificates and hardware tokens. `shipping_method` is `KEYLOCKER`: Creates a voucher that allows the requestor to choose a provisioning method of DigiCert KeyLocker (`keylocker`). Voucher cost includes price of both certificates and DigiCert KeyLocker. `shipping_method` is omitted: Creates a voucher that allows the requestor to choose a provisioning method of Use existing token (`client_app`) or Install on HSM (`email`). Voucher cost includes price of certificates only. Other products:`shipping_method` is not used. Omit from your request.
payment_method	required	string	Specify the payment method to use. Allowed values:`balance`, `card`, `wire_transfer`
credit_card	conditional	object	Object with information about the credit card charged for the order. Required if `payment_method` is card; otherwise, ignored.
.. number	required	string	Credit card number.
.. expiration_month	required	integer	Credit card expiration month. Format as a two-digit number between `01` (Jan) and `12` (Dec).
.. expiration_year	required	integer	Credit card expiration year. Format as a four-digit number. For example: `2026`
.. cvv	required	integer	Card verification value (CVV). Format as a three- or four-digit number. For example: `333` or `4444`
.. cardholder_name	required	string	Cardholder’s first and last name.
billing_address	conditional	object	Object with information about the billing address. Required if `payment_method` is `card`; otherwise, ignored.
.. address	required	string	Billing street address.
.. address2	optional	string	Continuation of street address.
.. city	required	string	Billing city.
.. state	conditional	string	Billing state or province. Optional for some countries.
.. country	required	string	Billing country.
.. zip	conditional	string	Billing zip or postal code. Optional for some countries.
billing_contact	conditional	object	Billing contact to use for wire transfers. Required if `payment_method` is `wire_transfer`; otherwise, ignored.
.. name	required	string	Billing contact name. Character limit: 128
.. organization_name	required	string	Billing contact organization name. Character limit: 128
.. country	required	string	Two-letter country code for the country where the billing contact resides. Format: Must be a valid ISO 3166-1 alpha-2 code.
.. address	required	string	Billing contact address. Character limit: 64
.. address2	optional	string	Continuation of billing contact address. Character limit: 64
.. city	required	string	Billing contact city. Character limit: 64
.. state	optional	string	Billing contact state or province. Character limit: 64
.. zip	required	integer	Billing contact zip or postal code. Character limit: 10
.. email	required	string	Billing contact email address. Character limit: 255
.. phone	optional	string	Billing contact phone number. Character limit: 32
name	optional	string	Include a customer name or organization that this voucher order is intended for. Only for tracking and order management purposes. Character limit:`128`
notes	optional	string	Include any notes that help you with order management. Character limit:`512`

Response parameters

Name	Type	Description
id	integer	Voucher order ID.
name	string	Voucher order name provided in request.
status	string	Status of Voucher order. Possible values:`active`, `used`, `canceled`
cost	number	Voucher order cost, without tax.
cost_plus_tax	number	Voucher order cost, with tax.
created_date	string	Date and time the voucher order was created. Format: `YYYY-MM-DD hh-mm-ss`
expiration_date	string	Date the voucher order expires. Format:`YYYY-MM-DD`
receipt_id	integer	Receipt ID. Returned when the `payment_method` for the order is `balance` or `card`. Not returned if `cost_plus_tax` is 0.
invoice_id	integer	Invoice ID. Returned when the `payment_method` for the order is `wire_transfer`. Not returned if `cost_plus_tax` is 0.
codes	array	List of objects with details about the voucher codes in this order. Each certificate in the order is returned as a separate object.
.. id	integer	Voucher code ID.
.. value	string	Unique voucher code.
.. product	object	Object with product details.
.. .. name_id	string	Name ID of the product. See Glossary – Product identifiers.
.. no_of_fqdns	integer	Number of FQDN SAN slots. Possible values: `0`-`250`. Note that the total number of SANs cannot exceed 250.
.. no_of_wildcards	integer	Number of Wildcard SAN slots. Possible values: `0`-`250`. Note that the total number of SANs cannot exceed 250.
.. validity_years	integer	Number of years the certificate is valid. Only returned if the order request used `validity_years` to set the validity period.
.. validity_days	integer	Number of days the certificate is valid. Only returned if the order request used `validity_days` to set the validity period.
.. status	string	Voucher code status.
notes	string	Notes provided in request to help you manage the voucher order.

In this section: