{
  "openapi": "3.0.3",
  "info": {
    "title": "VoucherVerse Codes API",
    "version": "1.0.0",
    "description": "Validate, allocate and redeem a campaign's voucher codes from any system. Docs: /docs/"
  },
  "servers": [
    {
      "url": "/",
      "description": "Same host as the dashboard"
    }
  ],
  "components": {
    "securitySchemes": {
      "campaignApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "The campaign's API key (vvb_...), from Campaigns > campaign > API access"
      },
      "merchantApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "A merchant user's API key"
      }
    }
  },
  "paths": {
    "/public/v1/codes/validate": {
      "post": {
        "summary": "Validate a code",
        "description": "Checks that a code exists and can be redeemed. Changes nothing.",
        "security": [
          {
            "campaignApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "participant"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Surrounding spaces and letter case are ignored"
                  },
                  "participant": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Stable ID of who is acting (phone number, your user ID, till ID). Used for rate limiting and recorded on the code."
                  }
                }
              },
              "example": {
                "code": "VVX7K2M9QP",
                "participant": "27821234567"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Outcome, including refusals (branch on ok/status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or missing fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, wrong or rotated API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error; retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public/v1/codes/allocate": {
      "post": {
        "summary": "Allocate a code",
        "description": "Gives a code to a recipient: the given pending code, or the next pending code when code is omitted. Give at least one of customerEmail, customerPhone, externalId.",
        "security": [
          {
            "campaignApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Letter case is ignored. Omit to take the next pending code"
                  },
                  "customerEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Stored and matched in lower case. An address that isn't a valid email is refused with 400"
                  },
                  "customerPhone": {
                    "type": "string",
                    "description": "Digits with the country code first (E.164; a leading + is optional, spaces and dashes are ignored). A local number starting with 0 is refused with 400",
                    "example": "27821234567"
                  },
                  "externalId": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Your own ID for the recipient, one line without control characters"
                  }
                }
              },
              "example": {
                "customerEmail": "jane@example.com",
                "externalId": "crm-10492"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Outcome, including refusals (branch on ok/status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ALLOCATED",
                        "NO_CODES_LEFT",
                        "NOT_FOUND",
                        "ALREADY_ALLOCATED",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string"
                    },
                    "value": {
                      "type": "number"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "customerId": {
                      "type": "string"
                    },
                    "externalId": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or missing fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ALLOCATED",
                        "NO_CODES_LEFT",
                        "NOT_FOUND",
                        "ALREADY_ALLOCATED",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string"
                    },
                    "value": {
                      "type": "number"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "customerId": {
                      "type": "string"
                    },
                    "externalId": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, wrong or rotated API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ALLOCATED",
                        "NO_CODES_LEFT",
                        "NOT_FOUND",
                        "ALREADY_ALLOCATED",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string"
                    },
                    "value": {
                      "type": "number"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "customerId": {
                      "type": "string"
                    },
                    "externalId": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error; retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ALLOCATED",
                        "NO_CODES_LEFT",
                        "NOT_FOUND",
                        "ALREADY_ALLOCATED",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string"
                    },
                    "value": {
                      "type": "number"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "customerId": {
                      "type": "string"
                    },
                    "externalId": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public/v1/codes/redeem": {
      "post": {
        "summary": "Redeem a code",
        "description": "Uses up a pending or allocated code. Each code can be redeemed once. If the campaign runs a prize draw, the redemption may win a prize: prize, prizeDescription and prizeCode say what, and message adds \"You won …!\".",
        "security": [
          {
            "campaignApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "participant"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Surrounding spaces and letter case are ignored"
                  },
                  "participant": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Stable ID of who is acting (phone number, your user ID, till ID). Used for rate limiting and recorded on the code."
                  }
                }
              },
              "example": {
                "code": "VVX7K2M9QP",
                "participant": "27821234567"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Outcome, including refusals (branch on ok/status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person. A prize win adds \"You won <prize>!\" and the prize code, if any"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or missing fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, wrong or rotated API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error; retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "status",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "true for VALID (validate) or REDEEMED (redeem)"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "VALID",
                        "REDEEMED",
                        "NOT_FOUND",
                        "ALREADY_REDEEMED",
                        "EXPIRED",
                        "CAMPAIGN_CLOSED",
                        "RATE_LIMITED",
                        "BAD_REQUEST",
                        "INVALID_KEY",
                        "ERROR"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "description": "The code as stored, when it was found"
                    },
                    "message": {
                      "type": "string",
                      "description": "Suggested reply to the person"
                    },
                    "prize": {
                      "type": "string",
                      "description": "Redeem in a campaign with a prize draw: the prize this redemption won, \"\" when it won nothing (status stays REDEEMED)"
                    },
                    "prizeDescription": {
                      "type": "string",
                      "description": "The prize's description, \"\" without one"
                    },
                    "prizeCode": {
                      "type": "string",
                      "description": "A code from another campaign given to the winner, when the prize comes with one; \"\" otherwise, or while it is still to follow"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public/campaigns/{campaignId}/vouchers/{code}/redeem": {
      "post": {
        "summary": "Redeem a code (merchant)",
        "description": "For tills and POS, authenticated with a merchant user's key.",
        "security": [
          {
            "merchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customerEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Stored and matched in lower case. An address that isn't a valid email is refused with 400"
                  },
                  "customerPhone": {
                    "type": "string",
                    "description": "Digits with the country code first (E.164; a leading + is optional, spaces and dashes are ignored). A local number starting with 0 is refused with 400",
                    "example": "27821234567"
                  },
                  "merchantId": {
                    "type": "string",
                    "description": "e.g. till or POS ID"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The redeemed voucher. In a campaign with a prize draw it may carry prize: { no, name, description, code, codeOwed, wonAt } (code is a prize code from another campaign; codeOwed means it is still to follow)"
          },
          "401": {
            "description": "Invalid merchant key"
          },
          "403": {
            "description": "Campaign not in the merchant's company"
          },
          "404": {
            "description": "No such code"
          },
          "402": {
            "description": "The company's VoucherVerse plan is unpaid or has ended"
          },
          "409": {
            "description": "Already redeemed, expired, or campaign inactive"
          }
        }
      }
    }
  }
}
