Spend Documents v4

Spend Documents v4 provides APIs for ingesting & retrieving receipts and compliance documents. Certified vendors, who have achieved compliance, are able to utilize these APIs to submit compliant receipts to the SAP Concur platform. The workflow involves vendors posting a display version of the receipt, accompanied by the necessary data to generate a receipt. Following this, they can use the PUT API to upload the compliance document. After a successful posting and processing of the receipts, available expenses or receipts are created in Concur Expense.

Prior Versions

The Spend Documents v4 API coexists with another set of Receipts V4 APIs. The latter is currently used for facilitating the submission of electronic receipts (eReceipts) to the SAP Concur platform.

Limitations

This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. To submit electronic receipts (eReceipts) please use the Receipts v4 APIs.

Products and Editions

Concur Expense Professional Edition
Concur Expense Standard Edition

Scope Usage

Name	Description	Endpoint
`spenddocs.receipts.write` `spenddocs.receipts.writeonly`	Post receipt for the user	POST
`spenddocs.receipts.read`	Retrieve Receipt and its representations either by Receipt Id or Image Id and company Id	GET
`spenddocs.receipts.compliance.read`	Retrieve compliance representation of the receipt	GET
`spenddocs.receipts.compliance.write` `spenddocs.receipts.compliance.writeonly`	Put compliance representation of the receipt	PUT

Post a New Receipt

This endpoint facilitates the creation of a new receipt. The data for the receipt should be supplied within the request body. Additionally, the display document for the receipt should be uploaded within the same request body, and the feature should be configured to ‘cfdi’.

Scopes

spenddocs.receipts.write spenddocs.receipts.writeOnly - Refer to Scope Usage for full details.

URI Template: /spend-documents/v4/receipts

Method: POST

Request

Name	Type	Format	Description
`receipt`	`object`	-	Required. The receipt data in JSON format.
`document`	`string`	-	The receipt document to be uploaded. Compatible formats are: PDF, JPEG, PNG, GIF, JPG.

Refer to the Receipt Schema for the structure of the receipt object.

Response

Success

Name	Type	Format	Description
`id`	`string`	-	UUID of the receipt.
`imageId`	`string`	-	Identifier for the image.
`href`	`string`	-	URI to retrieve the receipt.

Error

Name	Type	Format	Description
`timestamp`	`string`	-	Date and time.
`status`	`string`	-	HTTP status code.
`message`	`string`	-	Error message content.

Status Codes

Example

Request

curl -L -X POST 'https://us.api.concursolutions.com/spend-documents/v4/receipts' \ 
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json' \
-F 'image=@"1.jpg"' \
--F 'receipt="{
  "metadata": {
    "userId": "a9abaa60-38a0-46be-9736-bc9c1e317e41",
    "companyId": "fb7c8157-16d6-4dfd-b970-8c2a39d81790",
    "origin": "vendor",
    "feature": "cfdi",
    "category": "general"
  },
  "receiptData": {
    "transactionDateTime": "08/08/2022 3:30 PM",
    "amount": {
      "total": "18.47",
      "currency": "GBP",
      "subTotal": "15.05"
    },
    "vendor": {
      "name": "Amazon",
      "addressLine": "1234, Test street",
      "city": "seattle",
      "state": "washington",
      "country": "US",
      "postalCode": "98050",
      "taxId": "12ADAqweq",
      "phone": "4252322323"
    },
    "paymentType": {
      "method": "Credit Card",
      "creditCard": {
        "type": "MasterCard",
        "lastFour": "6170"
      }
    },
    "referenceNumber": "203-6291668-6997137",
    "lineItems": [
      {
        "title": "testTitle",
        "description": "KetoPlastics 1 ® 110 Litre Black Bin/Refuse Bin With Lockable Lid (Made In The UK)",
        "date": "2022-08-08T15:30:12-0500",
        "folioType": "00",
        "amount": "18.47",
        "quantity": "5",
        "unitPrice": "17.07",
        "subTotal": "15.05",
        "discounts": [
          {
            "discountAmount": "-2.02",
            "discountName": "Discount lineitem level"
          }
        ],
        "taxes": [
          {
            "amount": "3.42",
            "name": "Tax",
            "rate": 0.9
          }
        ],
        "additionalDescription": "Seller: Ketoplastics Limited",
        "semanticsCode": "OTHERS"
      }
    ],
    "discounts": [
      {
        "discountAmount": "-2.02",
        "discountName": "Discount receipt level"
      }
    ],
    "discountsTotal": "-2.33",
    "taxesTotal": "3.42",
    "tripDetails": {
      "itineraryLocator": "12345",
      "driverNumber": "ss-343",
      "travelDuration": "test",
      "mapUrl": "https://test.com",
      "startDate": "2014-11-10T15:08:24-0700",
      "endDate": "2014-11-10T15:39:46-0700",
      "classOfService": "Taxi Cab",
      "distance": {
        "totalDistance": 15.6,
        "unit": "mi"
      },
      "source": {
        "name": "start",
        "addressLine": "601 108th Ave NE",
        "city": "Bellevue",
        "country": "US",
        "postalCode": "98004"
      },
      "destination": {
        "name": "end",
        "addressLine": "1218 3rd Ave",
        "city": "Seattle",
        "country": "US",
        "postalCode": "98104"
      }
    }
  }
}"
' 

Response

202 Accepted

{
    "imageId": "341D9EFCDC4E3833B76F75CFC53FF2E9",
    "href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/3602e892-f463-497a-8654-8b2e802f4d65",
    "id": "3602e892-f463-497a-8654-8b2e802f4d65"
}

Compliance Document for an Existing Receipt

This endpoint facilitates the creation of a compliance document for an existing receipt. The compliance document should be uploaded within the request body.

Scopes

spenddocs.receipts.compliance.write
spenddocs.receipts.compliance.writeonly

Refer to Scope Usage for full details.

Request

URI Template: /spend-documents/v4/receipts/{receiptId}

Method: PUT

Parameters

Name	Type	Format	Description
`receiptId`	`string`	-	Required. The unique identifier (UUID) of the receipt.
`Type`	`string`	-	Required. cfdi.

Response

Success

Name	Type	Format	Description
`id`	`string`	-	UUID of the receipt.

Error

Name	Type	Format	Description
`timestamp`	`string`	-	Date and time.
`status`	`string`	-	HTTP status code.
`message`	`string`	-	Error message content.

Refer to the Receipt Schema for the structure of the receipt object.

Status Codes

Example

Request

curl --location --request PUT 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json' \
-F 'image=@"compliance.xml"

Response

{

    "id": "41545f0b-ebce-47b5-8233-1e6ef7f7b3c8"
}

Get Receipt

There are two endpoints to retrieve the details of a specific receipt.

By ReceiptId

This endpoint retrieves the details of a specific receipt using the receipt’s unique identifier (UUID).

By ImageId and CompanyId

This endpoint retrieves the details of a specific receipt using the companyId and imageId.

Scopes

spenddocs.receipts.read - Refer to Scope Usage for full details.

Request

URI Template:

By Receipt Id: /spend-documents/v4/receipts/{receiptId}
By Image Id and Company Id: /spend-documents/v4/receipts?imageId={imageId}&companyId={companyId}

Method: GET

Parameters

Name	Type	Format	Description
`receiptId` or `companyId` + `imageId`	string	-	Required. The unique identifier (UUID) of the receipt OR the unique identifier (UUID) of the company and identifier for the `imageId`.

Response

Success

Receipt Schema

Error

Name	Type	Format	Description
`timestamp`	`string`	-	Date and time.
`status`	`string`	-	HTTP status code.
`message`	`string`	-	Error message content.

Status Codes

Headers

concur-correlationid is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.

Payload

Receipt Response

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'

curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts?imageId=2AB8D2C8078C4E38A5E7F18A6DE5558D&companyId=71f74b81-bb57-4c54-8985-5d7c42f6feb1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'

Response

200 OK

{
  "metadata": {
    "userId": "3e2c1b7e-0969-41b1-b5a6-590eb6a5f885",
    "imageId": "F66F323EAC704DA3B3AA85F66D7E1663",
    "id": "4d3a8d80-0f93-4b0b-bed1-2724a354858c",
    "companyId": "8f8fd1d8-bbc6-4611-861d-af714a02275f",
    "dateTimeReceived": "2024-04-26T18:37:41.930Z",
    "origin": "mobile",
    "captureMethod": "cameraCapture",
    "provider": "user",
    "feature": "cfdi",
    "status": "processed",
    "compliance": {
      "status": "processed"
    }
  },
  "receiptData": {
    "transactionDateTime": "2023-12-30T11:30:00",
    "amount": {
      "total": "30.0",
      "currency": "USD"
    },
    "vendor": {
      "name": "KIRKLAND PERFORMANCE CENTER",
      "city": "KIRKLAND",
      "state": "WASHINGTON",
      "country": "US"
    },
    "paymentType": {
      "creditCard": {
        "type": "$$",
        "lastFour": "1006"
      }
    },
    "expenseData": {
      "expenseType": "PARKG"
    }
  },
  "documents": [
    {
      "representation": "display",
      "type": "application/pdf",
      "name": "fr_expenseit.pdf",
      "renderable": true,
      "href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/4d3a8d80-0f93-4b0b-bed1-2724a354858c/representations?type=display"
    },
    {
      "representation": "compliance",
      "type": "application/pdf",
      "name": "4d3a8d80-0f93-4b0b-bed1-2724a354858c.pdf",
      "renderable": true,
      "href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/4d3a8d80-0f93-4b0b-bed1-2724a354858c/representations?type=compliance"
    }
  ]
}

Get Receipt Representation

There are two endpoints to retrieve the receipt document (display or compliance) of a specific receipt.

By ReceiptId

Retrieves the receipt using the receipt’s unique identifier (UUID).

By ImageId and CompanyId

Retrieves the receipt using the companyId and imageId.

Scopes

spenddocs.receipts.read, spenddocs.compliance.read
Refer to Scope Usage for full details.

Request

URI Template:

By Receipt Id: /spend-documents/v4/receipts/{receiptId}/representations?type={display or compliance}
By Image Id and Company Id: /spend-documents/v4/receipts?imageId={imageId}&companyId={companyId}&type={display or compliance}

Method: GET

Parameters

Name	Type	Format	Description
`receiptId` or `companyId` + `imageId`	`string`	Required. The unique identifier (UUID) of the receipt OR the unique identifier (UUID) of the company and identifier for the `imageId`.
Type	string	Required display or compliance

Response

Success

Returns the image byte stream.

Error

Name	Type	Format	Description
`timestamp`	`string`	-	Date and time.
`status`	`string`	-	HTTP status code.
`message`	`string`	-	Error message content.

Status Codes

Payload

Receipt Response

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745/representations?type=display' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'

curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts?imageId=2AB8D2C8078C4E38A5E7F18A6DE5558D&companyId=71f74b81-bb57-4c54-8985-5d7c42f6feb1&/representations?type=compliance \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'

Response

HTTP/1.1 200 ok
Content-Type: image/png
Content-Length: 108842

Returns the image byte stream.

Schema

Receipt

Name	Type	Format	Description
`metadata`	`object`	-	Receipt API schema for metadata, receipt-data, `enrichmentData` and document (& representations).
`receiptData`	`object`	-	Receipt API schema for receipt data.

Metadata

Name	Type	Format	Description
`userId`	`string`	-	User’s UUID.
`forwardId`	`string`	-	Forward Id that clients provide.
`imageId`	`string`	-	Imaging Id in Imaging Service.
`id`	`string`	-	Receipt Id.
`companyId`	`string`	-	Company UUID.
`dateTimeReceived`	`string`	-	Date time of receipt uploaded.
`origin`	`string`	-	Origin of the request - supported origins listed below.
`captureMethod`	`string`	-	Type of the receipt capture method.
`provider`	`string`	-	Provider of the request - supported providers listed below.
`complianceCountryCode`	`string`	-	Compliance country code based on user group configuration.
`feature`	`string`	-	Feature enrichment for the receipt.
`status`	`string`	-	Receipt status.
`compliance`	`object`	-	Compliance information for the receipt.
`entityId`	`string`	-	Entity Code.
`category`	`string`	-	eReceipt category.

ReceiptData

Name	Type	Format	Description
`receiveDateTime`	`string`	-	Date/Time of the document received by customer.
`transactionDateTime`	`string`	-	Date/Time of the transaction.
`amount`	`object`	-	Transaction Amount - Total, Transaction Currency Code, Total Net Amount, Transaction Amount - Sub Total.
`vendor`	`object`	-	Vendor details: Name, Tax Id of the company/vendor, Address Line, City, State, Country, Postal Code, Phone.
`comments`	`string`	-	Comments can be added here for any receipt.
`paymentType`	object	-	Supported Payment types based on the data on the Receipt: Payment type method (enum: Cash, Credit Card, Digital Wallet), Credit card type if the payment method is credit card (Name of the card type ex: American Express, MasterCard, Discover, etc., Last 4 digits of credit card number if the payment method is credit card), if the payment method is digitalWallet, type of digital wallet (ex: ApplePay, PayTM, Rupay, GooglePay etc.).
`documentCompliance`	`object`	-	Document Compliance information: UUID of the Document, Version of the document format, Additional identified for the document, Document Type (only code), Codes supported by the document, Verification or Certificate Code.
`lineItems`	`array`	-	Array of LineItems: Line Identifier, Product Code of goods and services, Item Quantity, Item Unit Price, Item Tax Rate (optional), Item Sub Total (optional), Description, Date, Type, Amount, The taxes applied on this LineItem transaction, The discounts offered on this LineItem transaction, Additional Description, Indicates the charge category for the line item. Example: ‘MOVIE’, ‘PARKING’, ‘OTHER’ etc.
`expenseData`	`object`	-	Expense Data: Expense Type for Expense reimbursement, Payment type for Expense reimbursement.
`customData`	`object`	-	Custom Data.
`referenceNumber`	`string`	-	The unique receipt provider or vendor identifier for this receipt. This value can also be referred to as transaction number, check number, order ID or similar.
`discounts`	`array`	-	The discounts offered on this transaction.
`discountsTotal`	`string`	-	Total discounts.
`taxesTotal`	`string`	-	Total taxes.
`tripDetails`	`object`	-	Trip details, This includes all the trip/travel related information specific to an eReceipt category: Unique identifier of an itinerary (also know as a trip) in Concur Itinerary Service. An itinerary can contain one or more bookings from various sources, Unique identifier assigned by the ride company to a driver, Duration of the ride, Google Map url documenting the route taken, Trip starting Date/Time, Trip ending Date/Time, The class of the booking, Trip Distance (Total Distance, Unit of distance: km, mi), Source address which can be pickup location, departure etc., Destination address which can be drop location, arrival etc.
`programName`	`string`	-	Name of the program applied to the Receipt.
`networkTransactionId`	`string`	-	The network transaction id for the payment.
`taxes`	`array`	-	The taxes applied on this transaction.

Document Data

Name	Type	Format	Description
`representation`	`string`	-	For a given receipt document three representations can be stored in the system. Display – a downsized image version to cater for web and mobile UI, compliance - reflects the signed or certified or verified document, original - original document that was submitted.
`type`	`string`	-	File type of the receipt document, e.g., PDF, JPEG, PNG, GIF, JPG.
`name`	`string`	-	File name of the receipt document.
`renderable`	`boolean`	`true` / `false`	Boolean indicating whether the document can be rendered in UI.
`href`	`string`	-	Href to download the document.

Spend Documents v4

Prior Versions

Limitations

Products and Editions

Scope Usage

Post a New Receipt

Scopes

Request

Response

Success

Error

Status Codes

Example

Request

Response

Compliance Document for an Existing Receipt

Scopes

Request

Parameters

Response

Success

Error

Status Codes

Example

Request

Response

Get Receipt

By ReceiptId

By ImageId and CompanyId

Scopes

Request

Parameters

Response

Success

Error

Status Codes

Headers

Payload

Example

Request

Response

Get Receipt Representation

By ReceiptId

By ImageId and CompanyId

Scopes

Request

Parameters

Response

Success

Error

Status Codes

Payload

Example

Request

Response

Schema

Receipt

Metadata

ReceiptData

Document Data

On this page