Create a tax exemption certificate

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// `signed_id` comes from `client.files.upload(file, { visibility: 'private' })`.
const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
  certificate_number: 'DE-RESALE-7',
  tax_exemption_reason_id: 'txr_UkLWZg9DAJ',
  country_code: 'DE',
  document_signed_id: signed_id,
})

{
  "id": "cert_gbHJdmfrXB",
  "certificate_number": "DE-RESALE-7",
  "status": "pending",
  "issuing_authority": null,
  "metadata": {},
  "issued_at": null,
  "expires_at": null,
  "verified_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "company_id": "comp_UkLWZg9DAJ",
  "tax_exemption_reason_id": "txr_UkLWZg9DAJ",
  "country_code": "DE",
  "state_code": null,
  "active": false,
  "lapsed": false,
  "can_be_deleted": true,
  "document_filename": "resale.pdf",
  "document_byte_size": 20,
  "document_url": "/api/v3/admin/companies/comp_UkLWZg9DAJ/tax_exemption_certificates/cert_gbHJdmfrXB/download"
}

{
  "error": {
    "code": "validation_error",
    "message": "Certificate number can't be blank",
    "details": {
      "certificate_number": [
        {
          "code": "blank",
          "message": "can't be blank",
          "specific": false
        }
      ]
    }
  }
}

POST

api

admin

companies

{company_id}

tax_exemption_certificates

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// `signed_id` comes from `client.files.upload(file, { visibility: 'private' })`.
const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
  certificate_number: 'DE-RESALE-7',
  tax_exemption_reason_id: 'txr_UkLWZg9DAJ',
  country_code: 'DE',
  document_signed_id: signed_id,
})

{
  "id": "cert_gbHJdmfrXB",
  "certificate_number": "DE-RESALE-7",
  "status": "pending",
  "issuing_authority": null,
  "metadata": {},
  "issued_at": null,
  "expires_at": null,
  "verified_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "company_id": "comp_UkLWZg9DAJ",
  "tax_exemption_reason_id": "txr_UkLWZg9DAJ",
  "country_code": "DE",
  "state_code": null,
  "active": false,
  "lapsed": false,
  "can_be_deleted": true,
  "document_filename": "resale.pdf",
  "document_byte_size": 20,
  "document_url": "/api/v3/admin/companies/comp_UkLWZg9DAJ/tax_exemption_certificates/cert_gbHJdmfrXB/download"
}

{
  "error": {
    "code": "validation_error",
    "message": "Certificate number can't be blank",
    "details": {
      "certificate_number": [
        {
          "code": "blank",
          "message": "can't be blank",
          "specific": false
        }
      ]
    }
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Path Parameters

company_id

string

required

Body

application/json

certificate_number

string

required

Example:

"DE-RESALE-7"

tax_exemption_reason_id

string

required

One of the store's active tax exemption reasons. The tax provider receives its code.

issuing_authority

string | null

Example:

"Finanzamt Berlin"

issued_at

string<date-time> | null

expires_at

string<date-time> | null

country_code

enum<string> | null

Where the certificate holds. Omit it and state_code for one valid everywhere.

Available options:

AD,

AE,

AF,

AG,

AI,

AL,

AM,

AO,

AR,

AS,

AT,

AU,

AW,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BI,

BJ,

BL,

BM,

BN,

BO,

BQ,

BR,

BS,

BT,

BW,

BY,

BZ,

CA,

CC,

CD,

CF,

CG,

CH,

CI,

CK,

CL,

CM,

CN,

CO,

CR,

CU,

CV,

CW,

CX,

CY,

CZ,

DE,

DJ,

DK,

DM,

DO,

DZ,

EC,

EE,

EG,

ER,

ES,

ET,

FI,

FJ,

FK,

FM,

FO,

FR,

GA,

GB,

GD,

GE,

GF,

GG,

GH,

GI,

GL,

GM,

GN,

GP,

GQ,

GR,

GT,

GU,

GW,

GY,

HK,

HN,

HR,

HT,

HU,

ID,

IE,

IL,

IM,

IN,

IQ,

IR,

IS,

IT,

JE,

JM,

JO,

JP,

KE,

KG,

KH,

KI,

KM,

KN,

KP,

KR,

KW,

KY,

KZ,

LA,

LB,

LC,

LI,

LK,

LR,

LS,

LT,

LU,

LV,

LY,

MA,

MC,

MD,

ME,

MF,

MG,

MH,

MK,

ML,

MM,

MN,

MO,

MP,

MQ,

MR,

MS,

MT,

MU,

MV,

MW,

MX,

MY,

MZ,

NA,

NC,

NE,

NF,

NG,

NI,

NL,

NO,

NP,

NR,

NU,

NZ,

OM,

PA,

PE,

PF,

PG,

PH,

PK,

PL,

PM,

PN,

PR,

PS,

PT,

PW,

PY,

QA,

RE,

RO,

RS,

RU,

RW,

SA,

SB,

SC,

SD,

SE,

SG,

SH,

SI,

SJ,

SK,

SL,

SM,

SN,

SO,

SR,

SS,

ST,

SV,

SX,

SY,

SZ,

TC,

TD,

TG,

TH,

TJ,

TK,

TL,

TM,

TN,

TO,

TR,

TT,

TV,

TW,

TZ,

UA,

UG,

US,

UY,

UZ,

VA,

VC,

VE,

VG,

VI,

VN,

VU,

WF,

WS,

YE,

YT,

ZA,

ZM,

ZW

state_code

string | null

document_signed_id

string

A signed_id from files.upload() with visibility: 'private'.

metadata

object

Response

certificate created

⌘I

API basics

Endpoints

Authorizations

Headers

Path Parameters

Body

Response