---
updatedAt: 2026-10-06T16:12:47.000Z
agentTools:
projectIndex: https://developer.candis.io/llms.txt
---
# Create Goods Receipts
Import goods receipts from external systems
### Beta
This API is a beta feature and is subject to possible changes. The API response and functionality will be updated in the future.
| Request limit | Record limit | Batch size |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------- |
| 500 requests per minute per organization
2,500 per minute per holding | 120 records per minute per organization (burst 1,000)
150 per minute per holding (burst 1,500) | Maximum 100 records per request |
Both limits are evaluated on every request. A request is rejected when either is exceeded.
For requests containing the maximum of 100 records:
* Following an idle period, 10 consecutive requests are accepted without delay. This corresponds to the 1,000-record burst allowance.
* Sustained submission is subsequently paced at one request per 50 seconds, approximately 1.2 per minute.
* The allowance is restored to its ceiling after approximately 8 minutes without submissions.
[Rate Limiting Policy](/docs/rate-limiting-policy)
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"paths": {
"/v1/organizations/{organizationId}/imports/goods-receipts": {
"post": {
"description": "Import goods receipts from external systems",
"operationId": "createGoodsReceipts",
"parameters": [
{
"name": "organizationId",
"required": true,
"in": "path",
"description": "The organization ID.",
"schema": {
"example": "alpha-organization",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"receiptNumber": {
"type": "string",
"description": "Receipt number from your system. A generated ID from your system is fine.",
"example": "12312"
},
"amount": {
"description": "Total gross amount of the goods receipt, including all applicable taxes (VAT). Do not send the net amount — the value is treated as tax-inclusive.",
"allOf": [
{
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "Amount value",
"example": "100.258"
},
"currency": {
"type": "string",
"description": "Currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
]
},
"documentDate": {
"type": "string",
"description": "Document date",
"example": "2024-06-14T00:00:00Z"
},
"postingDate": {
"type": "string",
"description": "Posting date",
"example": "2024-07-01T00:00:00Z"
},
"dueDate": {
"type": "string",
"description": "Due date",
"example": "2024-07-15T00:00:00Z"
},
"accountsPayableNumber": {
"type": "string",
"description": "Accounts payable number",
"example": "102344"
},
"contactName": {
"type": "string",
"description": "Contact name",
"example": "VENDOR-001"
},
"goodsReceiptType": {
"type": "string",
"description": "Goods receipt type",
"example": "GOODS",
"enum": [
"GOODS",
"SERVICE"
]
},
"status": {
"type": "string",
"description": "Goods receipt status",
"example": "OPEN",
"enum": [
"OPEN",
"CLOSED"
]
},
"vendorReferenceNumber": {
"type": "string",
"description": "Vendor reference number",
"example": "REF-2024-001",
"nullable": true
},
"erpMetaData": {
"description": "Integration metadata",
"allOf": [
{
"type": "object",
"properties": {
"erpName": {
"type": "string",
"description": "Name of the ERP tool or integration system name from which the goods receipt originates",
"example": "BC365 or SAP_HANA"
},
"externalId": {
"type": "string",
"description": "Internal UUID of goods receipt in the integration system",
"example": "67890-223421-21312-123214"
},
"createdAt": {
"type": "string",
"description": "Datetime when the goods receipt was created in the ERP system",
"example": "2024-06-14T10:30:00Z",
"nullable": true
},
"updatedAt": {
"type": "string",
"description": "Datetime when the goods receipt was last updated in the ERP system",
"example": "2024-06-20T14:45:00Z",
"nullable": true
}
},
"required": [
"erpName",
"externalId"
]
}
]
},
"lineItems": {
"description": "Line items. Maximum 1000 per goods receipt.",
"type": "array",
"items": {
"type": "object",
"properties": {
"lineNumber": {
"type": "number",
"description": "Line number or sequence number from your system. A generated sequence from your system is fine.",
"example": 1
},
"itemNumber": {
"type": "string",
"description": "Item number or code from your system. For an ADDITIONAL_DELIVERY_COST (expense) line, the item code should be the expense code in the ERP or a similar unique identifier of that expense.",
"example": "PROD-001"
},
"type": {
"type": "string",
"description": "Type of the line item (ITEM, SERVICE, or ADDITIONAL_DELIVERY_COST). For SERVICE and ADDITIONAL_DELIVERY_COST, quantity, openQuantity, and unitPrice are optional; when omitted they are stored as quantity/openQuantity 1 and unitPrice = netAmount.",
"example": "ITEM",
"enum": [
"ITEM",
"SERVICE",
"ADDITIONAL_DELIVERY_COST"
]
},
"description": {
"type": "string",
"description": "Item description",
"example": "Screw"
},
"additionalDescription": {
"type": "string",
"description": "Additional description",
"example": "Type 123",
"nullable": true
},
"lineStatus": {
"type": "string",
"description": "Line item status",
"example": "OPEN",
"enum": [
"OPEN",
"CLOSED"
]
},
"generalLedgerAccount": {
"type": "string",
"description": "General ledger account code",
"example": "5000",
"nullable": true
},
"taxCode": {
"type": "string",
"description": "Tax code",
"example": "VAT19",
"nullable": true
},
"quantity": {
"type": "string",
"description": "Quantity. Required for ITEM lines. Optional for SERVICE and ADDITIONAL_DELIVERY_COST; when omitted, stored as 1 (with unitPrice = netAmount).",
"example": "10"
},
"openQuantity": {
"type": "string",
"description": "Open (remaining) quantity. Required for ITEM lines. Optional for SERVICE and ADDITIONAL_DELIVERY_COST; when omitted, stored as the resolved quantity (1 if quantity is also omitted).",
"example": "10"
},
"unitPrice": {
"type": "string",
"description": "Unit price with up to 9 decimals. Required for ITEM lines. Optional for SERVICE and ADDITIONAL_DELIVERY_COST; when omitted, stored as netAmount (with quantity 1).",
"example": "0.5445"
},
"netAmount": {
"type": "string",
"description": "Net amount (without tax) with 2 decimals",
"example": "54.45"
},
"taxAmount": {
"type": "string",
"description": "Tax amount with 2 decimals",
"example": "10.34"
},
"grossAmount": {
"type": "string",
"description": "Gross amount with 2 decimals",
"example": "64.79"
},
"costCenter": {
"type": "string",
"description": "Cost center (DIM 1 code)",
"example": "CC-001",
"nullable": true
},
"costObject": {
"type": "string",
"description": "Cost object (DIM 2 code)",
"example": "OBJ200",
"nullable": true
},
"customCostDimension": {
"type": "string",
"description": "Custom cost dimension (DIM 3 code)",
"example": "Berlin",
"nullable": true
},
"projectCode": {
"type": "string",
"description": "Project code",
"example": "PROJ-2024",
"nullable": true
},
"purchaseOrderMetadata": {
"description": "Purchase order metadata",
"nullable": true,
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"orderNumber": {
"type": "string",
"description": "Purchase order number from your system. A generated ID from your system is fine.",
"example": "PO-123"
},
"lineNumber": {
"type": "number",
"description": "Purchase order line number from your system. A generated sequence from your system is fine.",
"example": 1
},
"lineId": {
"type": "string",
"description": "Purchase order line ID from your system. A generated ID from your system is fine.",
"example": "zzzz-zzzzz-zzzz"
}
},
"required": [
"orderNumber"
]
}
]
},
"locationCode": {
"type": "string",
"description": "Location code",
"example": "LOC-001",
"nullable": true
},
"externalId": {
"type": "string",
"description": "External ID of the goods receipt line item from your system. A generated ID from your system is fine.",
"example": "EXT-GR-001",
"nullable": true
}
},
"required": [
"lineNumber",
"itemNumber",
"type",
"description",
"lineStatus",
"netAmount",
"taxAmount",
"grossAmount"
]
}
}
},
"required": [
"receiptNumber",
"amount",
"documentDate",
"postingDate",
"dueDate",
"accountsPayableNumber",
"contactName",
"goodsReceiptType",
"status",
"erpMetaData",
"lineItems"
]
}
}
}
}
},
"responses": {
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"processId": {
"type": "string",
"description": "The unique identifier of the import request.",
"example": "9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031"
}
},
"required": [
"processId"
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
},
"errors": {
"description": "This is an optional output that can provide more details about the input parameters that may have caused an issue.",
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "string",
"description": "This identifies the index of the payload that has an issue."
},
"property": {
"type": "string",
"description": "This identifies the parameter that has an issue."
},
"messages": {
"description": "This provides more details about the parameter that has an issue.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"property",
"messages"
]
}
}
},
"required": [
"errorCode",
"message"
]
}
}
}
},
"429": {
"description": "The request limit or the per-record limit for this endpoint has been exceeded. No records were imported, so the same request body can be resubmitted unchanged once the wait has elapsed.\n\nSee the [Rate Limiting Policy](https://developer.candis.io/docs/rate-limiting-policy) for the limits, response headers and retry guidance.",
"headers": {
"Retry-After": {
"description": "Whole seconds to wait before retrying. See the Rate Limiting Policy for how the value is derived.",
"schema": {
"type": "integer",
"example": 10
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
},
"limit": {
"type": "string",
"description": "Which limit rejected the request: the request limit, which counts requests, or the record limit, which meters the records in the request body.",
"enum": [
"request",
"record"
]
},
"scope": {
"type": "string",
"description": "Whose allowance was exhausted: the organization’s own, or the shared allowance of the holding it belongs to.",
"enum": [
"organization",
"holding"
]
}
},
"required": [
"errorCode",
"message"
]
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "The Error Code assigned to the issue encountered",
"enum": [
"UNAUTHORIZED",
"FORBIDDEN",
"BAD_REQUEST",
"SERVICE_UNAVAILABLE",
"INTERNAL_SERVER_ERROR",
"MISSING_REQUESTER_ID",
"BAD_INPUT",
"NOT_FOUND",
"EXPORTABLE_POSTINGS_NOT_FOUND",
"TOO_MANY_REQUEST",
"FAILED_TO_FETCH_DOWNLOAD_URL",
"FILE_NOT_FOUND"
]
},
"message": {
"type": "string",
"description": "Description about the issue encountered"
},
"requestId": {
"type": "string",
"description": "This is the unique identifier for the request."
}
},
"required": [
"errorCode",
"message"
]
}
}
}
}
},
"security": [
{
"bearer": []
}
],
"summary": "Create Goods Receipts",
"tags": [
"Core Data"
]
}
}
},
"info": {
"title": "Candis API",
"version": "1.0",
"description": "",
"contact": {},
"x-logo": {
"url": "https://www.candis.io/img/candis-logo-black.svg",
"altText": "Candis GmbH"
}
},
"servers": [
{
"url": "https://api.candis.io"
},
{
"description": "Candis API Authorization Server.",
"url": "https://id.my.candis.io/auth/realms/candis/protocol/openid-connect"
}
],
"components": {
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
}
}
}
}
```