# Create Voucher ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/products/{product_id}/vouchers/: post: summary: Create Voucher deprecated: false description: |- Adds a new voucher for a specified product. `products.read_write` - Products Read & Write operationId: add-product-voucher tags: - Default module/Apps/Merchant APIs/Products/Digital Vouchers - Digital Products parameters: - name: product_id in: path description: '' required: true example: a1477bb2-72ea-4be9-b2cf-093cefc721bb schema: type: string - name: Authorization in: header description: >- The Authorization token is a unique key given to the third-party application (Partner) by Zid. It is used to authenticate the API requests made by the Partner application. The token verifies the partner's identity and ensures they have permission to access Zid's API but does not provide any specific user or store information. It should be included in the header of API requests when the partner application needs to access Zid's API. required: true example: '{{Autherization}}' schema: type: string - name: Access-Token in: header description: >- An Access Token is a unique string that represents the authorization granted to a client (Partner application) by a user (Merchant or Store Manager) to access their protected resources. It is part of the OAuth 2.0 standard and is used to authenticate API requests on behalf of the user. Access Tokens have a limited lifespan and must be used within their validity period. Once expired, a new Access Token can be obtained using a Refresh Token. Access Tokens should be treated as sensitive information and must be kept secure to prevent unauthorized access to the user's data. If you do not have an `Access-Token`, but have the older alternative instead, i.e., the `X-Manager-Token`, then see the instructions [here](docs/Migrate-to-OAUTH-2.0.md) on how to obtain the `Access-Token`. required: true example: '{{Access-Token}}' schema: type: string - name: Store-Id in: header description: '' required: true example: '{{StoreId}}' schema: type: number examples: - 37213 - name: Role in: header description: Role of the user. required: true example: Manager schema: type: string enum: - Manager examples: - Manager - name: Accept-Language in: header description: >- Preferred language for the response. Defaults to `en` if not specified. required: false example: en schema: type: string enum: - en - ar examples: - en - name: Content-Type in: header description: >- The Media Type of the body of the request. This is used to describe the structure of the data in the body. required: true example: application/json schema: type: string default: application/json enum: - application/json - multipart/form-data - application/x-www-form-urlencoded requestBody: content: application/json: schema: type: object x-examples: Example 1: key: hehefgggghddfshhd serial_number: serial-number-1 pin_code: pin-code-example order: '1' expires_at: 2022-06-24T15:06:19+0000 status: SOLD required: - key - status properties: key: type: string description: >- The unique code sent to your customer to activate the digital product. This code is mandatory and is used to identify the voucher. examples: - ehefgggghddfshhd serial_number: type: string description: >- An optional field that serves as an identification code for the product or voucher, similar to an SKU (Stock Keeping Unit). examples: - serial-number-1 pin_code: type: string description: >- A secondary secret code used for some products that require an additional layer of security. This field is optional. examples: - pin-code-example order: type: string description: >- he unique identifier for the order associated with the voucher. examples: - '1' expires_at: type: string description: >- The expiration date of the voucher, if applicable. This field is optional and should be in a date format (e.g., "YYYY-MM-DD"). examples: - '"2022-06-24T15:06:19+0000"' status: type: string description: "The current status of the voucher. Possible values include:\r\n\r\n`AVAILABLE`: The voucher is available for use.\r\n`SOLD`: The voucher has been sold.\r\n`RESERVED`: The voucher is reserved for a customer.\r\n`RETURNED`: The voucher has been returned.\r\nThis field is mandatory." examples: - SOLD x-apidog-orders: - key - serial_number - pin_code - order - expires_at - status x-apidog-ignore-properties: [] example: key: key-2 serial_number: serial-number-2 pin_code: pin-code-example-2 expires_at: '2026-10-10 00:00:00' status: SOLD responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ProductVouchersSerializer' example: id: 3663992f-989e-4056-9a71-02a9109ec7fa product_id: a1477bb2-72ea-4be9-b2cf-093cefc721bb status: AVAILABLE order: null serial_number: serial-number-1 key: key-1 pin_code: pin-code-example expires_at: '2026-10-10T00:00:00Z' updated_at: '2026-02-11T12:39:55.597191Z' created_at: '2026-02-11T12:39:55.597152Z' headers: {} x-apidog-name: Created '400': description: '' content: application/json: schema: type: object properties: key: type: array items: type: string required: - key x-apidog-orders: - key x-apidog-ignore-properties: [] example: key: - The key 'key-1' already exists for this product! headers: {} x-apidog-name: Bad Request '401': description: '' content: application/json: schema: type: object description: >- Response returned when the request cannot be authenticated because the required credentials are missing, invalid, or expired. properties: status: type: string description: Indicates the overall status of the API response. examples: - error message: type: object description: >- Contains structured details explaining why the request could not be authenticated. properties: type: type: string description: Indicates the category of the response message. examples: - error code: type: string description: >- A machine-readable code identifying the authentication error. Returns null when no specific code is available. examples: - UNAUTHORIZED nullable: true name: type: string description: >- A short, human-readable title describing the authentication error. Returns null when no title is available. examples: - Unauthorized nullable: true description: type: string description: >- A human-readable explanation of why the request could not be authenticated. Returns null when no detailed explanation is available. examples: - >- Authentication credentials are missing, invalid, or expired. nullable: true required: - type - code - name - description x-apidog-orders: - type - code - name - description x-apidog-ignore-properties: [] required: - status - message x-apidog-orders: - status - message examples: - status: error message: type: error code: UNAUTHORIZED name: Unauthorized description: >- Authentication credentials are missing, invalid, or expired. x-apidog-ignore-properties: [] examples: '3': summary: Example 1 value: status: error message: type: error code: ERROR_SESSION_MISSING name: Sorry description: Please login first. '4': summary: Example 2 value: status: error message: type: error code: ERROR_SESSION_INVALID name: Sorry description: Login session expired. Please login again. '5': summary: Example 3 value: status: error message: type: error code: ERROR_SESSION_INVALID name: Sorry description: Invalid authentication headers: {} x-apidog-name: Unauthorized '415': description: '' content: application/json: schema: type: object properties: detail: type: string x-examples: Example 1: detail: الوسيط "" الموجود في الطلب غير معتمد. x-apidog-orders: - detail x-apidog-ignore-properties: [] headers: {} x-apidog-name: Unsupported Media Type '500': description: '' content: application/json: schema: type: object properties: status: type: string description: Status of the error. message: $ref: '#/components/schemas/ResponseEnvelopMessage' required: - status - message x-apidog-orders: - status - message x-apidog-ignore-properties: [] example: status: error message: type: error code: MSG_HIDDEN name: Error description: Internal Server Error headers: {} x-apidog-name: Internal Server error security: [] x-apidog-folder: Default module/Apps/Merchant APIs/Products/Digital Vouchers x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/613905/apis/api-9148644-run components: schemas: ProductVouchersSerializer: type: object properties: id: type: string description: Voucher ID product_id: type: string description: Related product ID status: type: string description: Voucher status order: type: integer description: Order ID nullable: true serial_number: type: string description: Unique serial nullable: true key: type: string description: Activation key pin_code: type: string description: PIN (if applicable) nullable: true expires_at: type: string description: Expiry timestamp nullable: true updated_at: type: string description: updated timestamps created_at: type: string description: created timestamps expires_at_formatted: type: string description: expiry timestamps nullable: true x-apidog-orders: - id - product_id - status - order - serial_number - key - pin_code - expires_at - updated_at - created_at - expires_at_formatted required: - id - product_id - status - order - serial_number - key - pin_code - expires_at - updated_at - created_at x-apidog-ignore-properties: [] x-apidog-folder: '' ResponseEnvelopMessage: type: object properties: type: type: string description: Type of response message returned by the API. examples: - success code: type: string description: Response code returned by the API, if available. examples: - MSG_POPUP_OK nullable: true name: type: string description: Name or title of the response message, if available. examples: - Coupons nullable: true description: type: string description: Detailed description of the response message, if available. examples: - Coupons created successfully nullable: true required: - type - code - name - description description: Additional response metadata. x-apidog-orders: - type - code - name - description x-apidog-ignore-properties: [] x-apidog-folder: '' securitySchemes: {} servers: - url: https://api.zid.sa/ description: Prod Env security: [] ```