{
  "openapi": "3.0.1",
  "info": {
    "title": "Voucherify API - Categories",
    "version": "v2018-08-01",
    "description": "Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details.",
    "contact": {
      "name": "Voucherify Team",
      "url": "https://www.voucherify.io/contact-support",
      "email": "support@voucherify.io"
    },
    "termsOfService": "https://www.voucherify.io/legal/subscription-agreement",
    "license": {
      "name": "MIT",
      "url": "https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://{cluster}.voucherify.io",
      "description": "Base URL",
      "variables": {
        "cluster": {
          "default": "api",
          "enum": [
            "api",
            "us1.api",
            "as1.api",
            "download",
            "us1.download",
            "as1.download"
          ]
        }
      }
    }
  ],
  "paths": {
    "/v1/categories": {
      "get": {
        "operationId": "list-categories",
        "tags": [
          "Categories"
        ],
        "summary": "List Categories",
        "description": "List all categories.",
        "parameters": [],
        "security": [
          {
            "X-App-Id": [],
            "X-App-Token": []
          },
          {
            "X-Voucherify-OAuth": [
              "api",
              "categories"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a dictionary of category objects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesListResponseBody"
                },
                "examples": {
                  "Example": {
                    "value": {
                      "object": "list",
                      "data_ref": "data",
                      "data": [
                        {
                          "id": "cat_0b5f49fb31c3bf6ab0",
                          "name": "Sixth",
                          "hierarchy": 6,
                          "created_at": "2022-07-13T06:21:36.852Z",
                          "object": "category"
                        },
                        {
                          "id": "cat_0b5f49e6e1ce5bd2ba",
                          "name": "Fifth",
                          "hierarchy": 5,
                          "created_at": "2022-07-13T06:21:16.039Z",
                          "object": "category"
                        },
                        {
                          "id": "cat_0b5f49deafce5bd2b5",
                          "name": "Fourth",
                          "hierarchy": 4,
                          "created_at": "2022-07-13T06:21:07.662Z",
                          "object": "category"
                        },
                        {
                          "id": "cat_0b5f49d45c43bf6a99",
                          "name": "Third",
                          "hierarchy": 3,
                          "created_at": "2022-07-13T06:20:57.094Z",
                          "object": "category"
                        },
                        {
                          "id": "cat_0b5f3f9881ce5bccb6",
                          "name": "Second",
                          "hierarchy": 2,
                          "created_at": "2022-07-13T05:36:14.355Z",
                          "object": "category"
                        },
                        {
                          "id": "cat_0b53bc388dc2f108ba",
                          "name": "First",
                          "hierarchy": 1,
                          "created_at": "2022-07-04T06:58:57.734Z",
                          "object": "category"
                        }
                      ],
                      "total": 6
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-category",
        "tags": [
          "Categories"
        ],
        "summary": "Create Category",
        "description": "Create category with a specific name and hierarchy.",
        "parameters": [],
        "security": [
          {
            "X-App-Id": [],
            "X-App-Token": []
          },
          {
            "X-Voucherify-OAuth": [
              "api",
              "categories"
            ]
          }
        ],
        "requestBody": {
          "description": "Specify the details of the category that you would like to create.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CategoriesCreateRequestBody"
              },
              "examples": {
                "Example": {
                  "value": {
                    "name": "Eighth",
                    "hierarchy": 8
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Returns a newly created category object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesCreateResponseBody"
                },
                "examples": {
                  "Example": {
                    "value": {
                      "id": "cat_0b8b5a427a0283c854",
                      "name": "Eighth",
                      "hierarchy": 8,
                      "created_at": "2022-08-16T11:45:54.171Z",
                      "object": "category"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Returns an error if the payload is incomplete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/e_400_invalid_payload"
                },
                "examples": {
                  "Missing name": {
                    "value": {
                      "code": 400,
                      "key": "invalid_payload",
                      "message": "Invalid payload",
                      "details": "Payload should have required property 'name'",
                      "request_id": "v-0b8b5b960990210b25"
                    }
                  },
                  "Missing hierarchy": {
                    "value": {
                      "code": 400,
                      "key": "invalid_payload",
                      "message": "Invalid payload",
                      "details": "Payload should have required property 'hierarchy'",
                      "request_id": "v-0b8b5bf9d9c6824a2f"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/categories/{categoryId}": {
      "parameters": [
        {
          "schema": {
            "$ref": "#/components/schemas/ParameterCategoryId"
          },
          "name": "categoryId",
          "in": "path",
          "required": true,
          "description": "Unique category ID assigned by Voucherify."
        }
      ],
      "get": {
        "operationId": "get-category",
        "tags": [
          "Categories"
        ],
        "summary": "Get Category",
        "description": "Retrieve a category by the category ID.",
        "parameters": [],
        "security": [
          {
            "X-App-Id": [],
            "X-App-Token": []
          },
          {
            "X-Voucherify-OAuth": [
              "api",
              "categories"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a category object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesGetResponseBody"
                },
                "examples": {
                  "Example": {
                    "value": {
                      "id": "cat_0b5f49fb31c3bf6ab0",
                      "name": "Sixth",
                      "hierarchy": 6,
                      "created_at": "2022-07-13T06:21:36.852Z",
                      "object": "category"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete-category",
        "tags": [
          "Categories"
        ],
        "summary": "Delete Category",
        "description": "Delete a category by the category ID.",
        "parameters": [],
        "security": [
          {
            "X-App-Id": [],
            "X-App-Token": []
          },
          {
            "X-Voucherify-OAuth": [
              "api",
              "categories"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "No content is returned."
          },
          "404": {
            "description": "Returns an error indicating that the category with given ID was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "Not Found": {
                    "value": {
                      "code": 404,
                      "key": "not_found",
                      "message": "Resource not found",
                      "details": "Cannot find category with id example_category",
                      "request_id": "v-0b8b49205f902176c9",
                      "resource_id": "example_category",
                      "resource_type": "category"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "update-category",
        "tags": [
          "Categories"
        ],
        "summary": "Update Category",
        "description": "Update a category using the category ID.",
        "parameters": [],
        "security": [
          {
            "X-App-Id": [],
            "X-App-Token": []
          },
          {
            "X-Voucherify-OAuth": [
              "api",
              "categories"
            ]
          }
        ],
        "requestBody": {
          "description": "Specify the details of the category that you would like to update.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CategoriesUpdateRequestBody"
              },
              "examples": {
                "Example": {
                  "value": {
                    "name": "Summer",
                    "hierarchy": 1
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Returns a category object with a refreshed `updated_at` property.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoriesUpdateResponseBody"
                },
                "examples": {
                  "Example": {
                    "value": {
                      "id": "cat_0b60cfe7d0d7ddbb55",
                      "name": "Update",
                      "hierarchy": 1,
                      "created_at": "2022-07-14T10:45:13.156Z",
                      "updated_at": "2022-08-16T11:03:54.727Z",
                      "object": "category"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Returns an error indicating an invalid payload if the required request body parameters were not included in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/e_400_invalid_payload"
                },
                "examples": {
                  "Missing hierarchy": {
                    "value": {
                      "code": 400,
                      "key": "invalid_payload",
                      "message": "Invalid payload",
                      "details": "Payload should have required property 'hierarchy'",
                      "request_id": "v-0b8b4e6b6210217c93"
                    }
                  },
                  "Missing name": {
                    "value": {
                      "code": 400,
                      "key": "invalid_payload",
                      "message": "Invalid payload",
                      "details": "Payload should have required property 'name'",
                      "request_id": "v-0b8b4f418390217d82"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CategoriesListResponseBody": {
        "title": "Categories List Response Body",
        "type": "object",
        "description": "Response body schema for **GET** `v1/categories`.",
        "properties": {
          "object": {
            "type": "string",
            "default": "list",
            "enum": [
              "list"
            ],
            "description": "The type of the object represented by JSON. This object stores information about categories in a dictionary."
          },
          "data_ref": {
            "type": "string",
            "default": "data",
            "enum": [
              "data"
            ],
            "description": "Identifies the name of the attribute that contains the array of category objects."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of categories."
          }
        },
        "required": [
          "object",
          "data_ref",
          "data",
          "total"
        ]
      },
      "CategoriesCreateRequestBody": {
        "title": "Categories Create Request Body",
        "type": "object",
        "description": "Request body schema for **POST** `v1/categories`.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Category name."
          },
          "hierarchy": {
            "type": "integer",
            "description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
            "minimum": 0
          }
        },
        "required": [
          "name",
          "hierarchy"
        ]
      },
      "CategoriesCreateResponseBody": {
        "title": "Categories Create Response Body",
        "description": "Response body schema for **POST** `v1/categories`.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique category ID assigned by Voucherify."
          },
          "name": {
            "type": "string",
            "description": "Category name."
          },
          "hierarchy": {
            "type": "integer",
            "description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
            "minimum": 0
          },
          "object": {
            "type": "string",
            "default": "category",
            "enum": [
              "category"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.",
            "example": "2022-07-14T10:45:13.156Z",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "hierarchy",
          "created_at",
          "object"
        ]
      },
      "e_400_invalid_payload": {
        "title": "Invalid Payload",
        "type": "object",
        "description": "Error: Bad Request → Invalid Payload",
        "properties": {
          "code": {
            "type": "integer",
            "default": 400,
            "description": "Error's HTTP status code."
          },
          "key": {
            "type": "string",
            "default": "invalid_payload",
            "description": "Short string describing the kind of error which occurred."
          },
          "message": {
            "type": "string",
            "default": "Invalid payload",
            "description": "A human-readable message providing a short description of the error."
          },
          "details": {
            "type": "string",
            "description": "A human-readable message providing more details about the error."
          },
          "request_id": {
            "type": "string",
            "example": "v-0a884c6be8c3756f42",
            "description": "This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team."
          }
        }
      },
      "CategoriesGetResponseBody": {
        "type": "object",
        "title": "Categories Get Response Body",
        "description": "Response body schema for **GET** `v1/categories/{categoryId}`.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Category"
          }
        ]
      },
      "ParameterCategoryId": {
        "type": "string",
        "example": "cat_0bb81a481615a37b5e"
      },
      "Error": {
        "title": "Error Object",
        "type": "object",
        "description": "Error details",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error's HTTP status code."
          },
          "key": {
            "type": "string",
            "description": "Short string describing the kind of error which occurred."
          },
          "message": {
            "type": "string",
            "description": "A human-readable message providing a short description of the error."
          },
          "details": {
            "type": "string",
            "description": "A human-readable message providing more details about the error."
          },
          "request_id": {
            "type": "string",
            "example": "v-0a885062c80375740f",
            "description": "This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team."
          },
          "resource_id": {
            "type": "string",
            "description": "Unique resource ID that can be used in another endpoint to get more details.",
            "example": "rf_0c5d710a87c8a31f86"
          },
          "resource_type": {
            "type": "string",
            "description": "The resource type.",
            "example": "voucher"
          },
          "error": {
            "type": "object",
            "description": "Includes additional information about the error.",
            "properties": {
              "message": {
                "type": "string",
                "description": "The message configured by the user in a validation rule."
              }
            }
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "CategoriesUpdateRequestBody": {
        "title": "Categories Update Request Body",
        "description": "Request body schema for **PUT** `v1/categories/{categoryId}`.",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Category name."
          },
          "hierarchy": {
            "type": "integer",
            "description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
            "minimum": 0
          }
        },
        "required": [
          "name",
          "hierarchy"
        ]
      },
      "CategoriesUpdateResponseBody": {
        "title": "Categories Update Response Body",
        "description": "Response body schema for **PUT** `v1/categories/{categoryId}`.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique category ID assigned by Voucherify."
          },
          "name": {
            "type": "string",
            "description": "Category name."
          },
          "hierarchy": {
            "type": "integer",
            "description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
            "minimum": 0
          },
          "object": {
            "type": "string",
            "default": "category",
            "enum": [
              "category"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.",
            "example": "2022-07-14T10:45:13.156Z",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "example": "2022-08-16T10:52:08.094Z",
            "description": "Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "hierarchy",
          "created_at",
          "object",
          "updated_at"
        ]
      },
      "Category": {
        "title": "Category",
        "description": "This is an object representing a category.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique category ID assigned by Voucherify."
          },
          "name": {
            "type": "string",
            "description": "Category name."
          },
          "hierarchy": {
            "type": "integer",
            "description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
            "minimum": 0
          },
          "object": {
            "type": "string",
            "default": "category",
            "enum": [
              "category"
            ],
            "description": "The type of the object represented by the JSON. This object stores information about the category."
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.",
            "example": "2022-07-14T10:45:13.156Z",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "example": "2022-08-16T10:52:08.094Z",
            "description": "Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "hierarchy",
          "created_at",
          "object"
        ]
      }
    },
    "securitySchemes": {
      "X-App-Id": {
        "type": "apiKey",
        "name": "X-App-Id",
        "in": "header"
      },
      "X-App-Token": {
        "type": "apiKey",
        "name": "X-App-Token",
        "in": "header"
      },
      "X-Voucherify-OAuth": {
        "type": "oauth2",
        "flows": {
          "implicit": {
            "authorizationUrl": "https://api.voucherify.io/v1/oauth/token",
            "scopes": {
              "api": "Gives access to whole server-side API.",
              "vouchers": "Gives access to all endpoints and methods starting with `v1/vouchers`.",
              "client_api": "Gives access to whole client-side API.",
              "client_vouchers": "Gives access to all endpoints and methods starting with `/client/v1/vouchers`.",
              "promotions": "Gives access to all endpoints and methods starting with `/v1/promotions`.",
              "client_promotions": "Gives access to all endpoints and methods starting with `/client/v1/promotions`",
              "campaigns": "Gives access to all endpoints and methods starting with `v1/campaigns`.",
              "client_publish": "Gives access to all endpoints and methods starting with `/client/v1/publish`.",
              "exports": "Gives access to all endpoints and methods starting with `/v1/exports`.",
              "publications": "Gives access to all endpoints and methods starting with `/v1/publications`.",
              "client_validate": "Gives access to all endpoints and methods starting with `/client/v1/validate`.",
              "validations": "Gives access to all endpoints and methods starting with `/v1/validations`.",
              "client_validations": "Gives access to all endpoints and methods starting with `/client/v1/validations`.",
              "qualifications": "Gives access to all endpoints and methods starting with `/v1/qualifications`.",
              "client_qualifications": "Gives access to all endpoints and methods starting with `/client/v1/qualifications`.",
              "client_redeem": "Gives access to all endpoints and methods starting with `/client/v1/redeem",
              "redemptions": "Gives access to all endpoints and methods starting with `/v1/redemptions`.",
              "client_redemptions": "Gives access to all endpoints and methods starting with `/client/v1/redemptions`",
              "customers": "Gives access to all endpoints and methods starting with `/v1/customers`.",
              "client_customers": "Gives access to all endpoints and methods starting with `/client/v1/customers`.",
              "orders": "Gives access to all endpoints and methods starting with `/v1/orders`.",
              "products": "Gives access to all endpoints and methods starting with `/v1/products`.",
              "skus": "Gives access to all endpoints and methods starting with `/v1/SKUs`.",
              "validation-rules": "Gives access to all endpoints and methods starting with `/v1/validation-rules`.",
              "validation-rules-assignments": "Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments",
              "segments": "Gives access to all endpoints and methods starting with `/v1/segments`.",
              "events": "Gives access to all endpoints and methods starting with `/v1/events`.",
              "client_events": "Gives access to all endpoints and methods starting with `client/v1/events`.",
              "rewards": "Gives access to all endpoints and methods starting with `/v1/rewards`.",
              "assets": "Gives access to all endpoints and methods starting with `/v1/assets`.",
              "task-results": "Gives access to all endpoints and methods starting with `/v1/task-results`.",
              "loyalties": "Gives access to all endpoints and methods starting with `/v1/loyalties`.",
              "client_consents": "Gives access to all endpoints and methods starting with `client/v1/consents`.",
              "consents": "Gives access to all endpoints and methods starting with `/v1/consents`.",
              "async-actions": "Gives access to all endpoints and methods starting with `/v1/async-actions`.",
              "product-collections": "Gives access to all endpoints and methods starting with `/v1/product-collections`.",
              "categories": "Gives access to all endpoints and methods starting with `/v1/categories`.",
              "metadata-schemas": "Gives access to all endpoints and methods starting with `/v1/metadata-schemas`.",
              "locations": "Gives access to all endpoints and methods starting with `/v1/locations`.",
              "referrals": "Gives access to all endpoints and methods starting with `/v1/referrals`.",
              "trash-bin": "Gives access to all endpoints and methods starting with `/v1/trash-bin`.",
              "templates": "Gives access to all endpoints and methods starting with `/v1/templates`."
            }
          }
        }
      }
    }
  }
}