Shipper · CustomsBeta

Customs Clearance API

The Betakom customs portal as an API, for business customers with an approved customs profile. Create a draft case, upload the papers, submit it, then poll it for status, the MRN and the documents our customs team issues (export accompanying document, exit confirmation, transit document, …). Requests run through exactly the same checks as the customer portal — lane rules, required papers, the credit line, today's tariff — and our customs team is notified the moment a case is submitted. Authenticate with a per-company API key that the company owner creates in the customer dashboard under Customs › API. Customs is offered for Germany: export from DE, import into DE, transit with one end in DE. There is no sandbox: every API key is live. Test with drafts — they are free, only your company sees them, and DELETE /cases/{id} discards them. Submitting a case files a real customs request with our team and is billed.

Diese API befindet sich in der Beta: Endpunkte und Felder können sich noch ändern.

Ressourcentypen

Case status

draft → pending (submitted) → in_progress (our team is working on it) ⇄ needs_customer (we asked you something) → finished | cancelled.

FieldTypeRequiredDescription
draftstatusoptionalCreated via API or portal, not yet submitted. Only you see it.
pendingstatusoptionalSubmitted; waiting for our customs team. You may still cancel.
in_progressstatusoptionalOur customs team is processing it.
needs_customerstatusoptionalWe need something from you — see the latest message with kind = question.
finishedstatusoptionalDone; mrn and deliverables are filled.
cancelledstatusoptionalWithdrawn by you or by us (cancelReason).

Errors

Every error is JSON: { success: false, code, message }. Branch on code, not on message.

FieldTypeRequiredDescription
401 api_key_missing / api_key_invalidauthoptionalNo key sent, or the key is unknown, revoked, or its creator no longer belongs to the company.
403 business_only / insufficient_scope / account_blockedauthoptionalThe key cannot use this API.
403 profile_not_approvedcustomsoptionalThe customs profile is not approved yet.
429 rate_limitedlimitoptionalMore than 120 requests per minute for this key. Retry after the Retry-After header.
503 service_unavailablelimitoptionalA short outage on our side. Safe to retry after the Retry-After header (seconds).
GET/api/v1/customs/catalog

Reference data: procedures, required papers, codes, upload limits

What a valid request looks like, served from the same constants the server validates against: per procedure the lane rule, the document slots (and which are required) and the documents Betakom returns; transit / origin-proof types, transport modes, case statuses, EU member states, upload size and MIME types.

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
GET/api/v1/customs/profile

Your company's customs profile

canFile = true once the customs profile (EORI + signed power of attorney) is approved — only then can cases be created. canImport = true when a deferment account is approved (needed for imports). The profile itself is maintained in the customer dashboard.

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
GET/api/v1/customs/cases/price-preview

Price a case before creating it

Query-Parameter

FieldTypeRequiredDescription
procedurestringrequiredexport | import | transit | origin_proof
positionsintegeroptionalNumber of goods positions (default 1).
tariffNumbersintegeroptionalNumber of distinct tariff numbers (default 1).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
  • Returns the tariff, the price breakdown and whether your credit line covers it (credit.sufficient).
GET/api/v1/customs/cases

List your cases

All cases of the company, drafts first, newest first, as summaries (status, mrn, priceTotal, documentsCount, deliverablesCount, requiredMissing, hasUnread).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
POST/api/v1/customs/cases

Create a draft case

Creates a DRAFT with the shipment details. Nothing reaches our customs team until you submit it. Requires an approved customs profile (403 profile_not_approved otherwise).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.

Body-Parameter

FieldTypeRequiredDescription
procedurestringrequiredexport | import | transit | origin_proof
originCountrystringrequiredISO 3166-1 alpha-2, e.g. DE. See /catalog for the lane rule of each procedure.
destinationCountrystringrequiredISO 3166-1 alpha-2, e.g. US.
transitTypestringoptionalT1 | T2 | T2F — required when procedure = transit.
originProofTypestringoptionalEUR1 | EUR_MED | ATR | REX | IHK — required when procedure = origin_proof.
customerReferencestringoptionalYour reference (max 80 chars), e.g. your order number.
goodsDescriptionstringoptionalShort description of the goods (max 500 chars).
transportModestringoptionalroad | sea | air | rail
plannedDatestringoptionalYYYY-MM-DD — planned shipping date.
positionsCountintegeroptionalGoods positions, 1–999 (default 1). Affects the price.
tariffNumbersCountintegeroptionalDistinct tariff numbers, 1–999 (default 1). Affects the price.
customerNotestringoptionalNote for our customs team (max 2000 chars).
cURL
curl -X POST 'https://betakom.de/api/v1/customs/cases' \
  -H "Authorization: Bearer $BETAKOM_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "procedure": "export",
    "originCountry": "DE",
    "destinationCountry": "US",
    "customerReference": "PO-4711",
    "goodsDescription": "Machine parts",
    "transportMode": "road",
    "positionsCount": 3,
    "tariffNumbersCount": 2
  }'
  • Validation errors return 400 with a code, e.g. lane_export_origin_de, lane_export_destination_third, transit_type_invalid, counts_invalid.
GET/api/v1/customs/cases/{id}

Get a case: status, MRN, documents, messages

The full case: status, mrn, exitConfirmedAt, price, the document slots with your files, deliverables (documents from Betakom — download them with /documents/download), and the message thread (kind = question is a query from our customs team; answer it with /messages). Poll this endpoint to follow a case; a few minutes between polls is plenty.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
PATCH/api/v1/customs/cases/{id}

Edit a draft

Same body as POST /cases. Drafts only (409 otherwise).

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
DELETE/api/v1/customs/cases/{id}

Discard a draft

Deletes a draft that was never submitted. A submitted case is withdrawn with /cancel instead.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
POST/api/v1/customs/cases/{id}/documents

Upload papers

multipart/form-data with one or more `file` parts and an optional `slot` (see /catalog for the slots of each procedure; omit it to leave the files unassigned). Allowed while the case is draft, pending, in_progress or needs_customer. An upload on a needs_customer case answers our query and puts the case back to in_progress.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.

Body-Parameter

FieldTypeRequiredDescription
filebinaryrequiredThe paper(s). Repeat the part for several files. PDF, images, Excel, Word or CSV; max 15 MB each.
slotstringoptionale.g. commercial_invoice, packing_list, transport_document.
cURL
curl -X POST 'https://betakom.de/api/v1/customs/cases/123/documents' \
  -H "Authorization: Bearer $BETAKOM_API_KEY" \
  -F 'slot=commercial_invoice' \
  -F 'file=@invoice.pdf'
  • PATCH /api/v1/customs/cases/{id}/documents { docId, slot } moves a file to another slot; DELETE ?docId=N removes one (draft and pending only).
GET/api/v1/customs/cases/{id}/documents/download

Download a paper or a Betakom document

Streams one file of the case — yours or one of the deliverables (export accompanying document, exit confirmation, …). docId is the document's id from the case detail.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Query-Parameter

FieldTypeRequiredDescription
docIdintegerrequiredDocument id (slots[].files[].id or deliverables[].id).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
POST/api/v1/customs/cases/{id}/submit

Submit a draft

Live — there is no sandbox: this files a real customs request with our team and is billed. Turns the draft into a pending case at today's tariff and reserves the price on your credit line. Checks: every required slot holds a file (400 required_documents_missing, with the missing slots), a credit line exists and covers the price (402 no_credit_line / insufficient_credit). On success our customs team is notified immediately and the key's creator receives the confirmation e-mail.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.
cURL
curl -X POST 'https://betakom.de/api/v1/customs/cases/123/submit' \
  -H "Authorization: Bearer $BETAKOM_API_KEY"
POST/api/v1/customs/cases/{id}/cancel

Withdraw a pending case

Only while the case is pending (our team has not started yet); releases the reserved credit. Once work has begun, ask our team via /messages.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.

Body-Parameter

FieldTypeRequiredDescription
reasonstringoptionalOptional reason (max 500 chars).
POST/api/v1/customs/cases/{id}/messages

Answer a query or add a note

Writes into the case thread and returns the updated case. A reply on a needs_customer case puts it back in front of our customs team.

Pfadparameter

FieldTypeRequiredDescription
idintegerrequiredThe case id (data.id from POST /cases).

Header

FieldTypeRequiredDescription
AuthorizationstringrequiredBearer bk_live_… — the company's API key (customer dashboard › Customs › API). X-API-Key: bk_live_… is accepted too.

Body-Parameter

FieldTypeRequiredDescription
bodystringrequiredThe message text.