Ledger and Factoring

Invoice - DRAFT API

Integrate to PayEx Billing Invoice API 

Changelog

VersionDateDescriptionCreated by
1.02025-05-20

Created document

Anders Göthberg
1.1 API in productionAnders Göthberg

Introduction

Link to the general step-by-step implementations guide that guides you through setting up a REST API integration towards PayEx Ledger Invoice Service can be found here 

Billing Invoice API presents presents at the lowest level all incoming charges that generated an invoice regardless of presentation in PDF. This can be used for presentation on the company's various applications such as "my pages" or customer service users in the company's own CRM.

Invoice API

1779266755446-810.png

Route description

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parent resources in the route.
lf-api.payex.com/billing/{subdomain}/v1/{ownerNo}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Route segmentDescription
subdomainIn this part of the API it will be "billing"
ownerNoThe ledger identifier/number at PayEx
resource1IdIdentifier of resource1 (invoices)
resource2Ididentifier of resource2, subresource to resource1 (customer recurring products or subscriptions)
resource3Ididentifier of resource3, subresource to resource2 (subscription recurring products)

Routes that occurs in examples of this documentation will use the following identifiers

ResourceIdentifier
ownerNoThe ledger identifier/number at PayEx
customerNoCustomer number
invoiceNoInvoice number
subscriptionNoSubscription number (identifier for subscription)
recurring-productsRecurring products on customer or subscription level

1. Customers

Get customer

1.1 Get specific Customer

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "customerNo": "15615616",
 "recurringProducts": "/billing/customer/v1/xxx/customers/15615616/recurring-products",
 "subscriptions": "/billing/customer/v1/xxx/customers/15615616/subscriptions",
 "operations": [
    {
     "rel": "add-subscription",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/subscriptions"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/recurring-products"
    }
  ]
}

1.2 Create Customer

Adds customer

Request
POST /billing/customer/v1/{ownerNo}/customers HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property Data typeFormatRequiredDescription
customerNo string MinLength: 1
MaxLength: 15
Regex pattern:"[a-zA-Z0-9äåöÄÅÖ&/_ -.]*"		Yes Identifier for customer
Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "customerNo": "15615616",
 "recurringProducts": "/billing/customer/v1/xxx/customers/15615616/recurring-products",
 "subscriptions": "/billing/customer/v1/xxx/customers/15615616/subscriptions",
 "operations": [
    {
     "rel": "add-subscription",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/subscriptions"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/15615616/recurring-products"
    }
  ],
 "@id": "/billing/customer/v1/xxx/customers/15615616"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
customerNo string  Identifier for customer
recurringProducts dynamic   Uri for selected recurrent lines
subscriptions dynamic   Uri for selected subscriptios
operations array  List of operations for this resource. See the documentation for more information. hypermedia part of the response

2. Recurring-products

Lists recurring products on customer level

2.1 Get list of Recurring-products

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of recurring products on customer level

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "recurringProductId": "4444",
     "baseProductCode": "F01",
     "deviantText": "Fakturaavgift",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "29.000",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    },
    {
     "recurringProductId": "4455",
     "baseProductCode": "P02",
     "deviantText": "Halvförsäkring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4455"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4455"
    }
  ],
 "navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products"
  }
}

Get specific recurring product on customer level

2.2 Get specific Recurring-product

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a specific recurring product

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "recurringProductId": "4444",
 "baseProductCode": "F01",
 "deviantText": "Fakturaavgift",
 "startDate": "YYYY-MM-DD",
 "endDate": "YYYY-MM-DD",
 "deviantPrice": "29.000",
 "deviantInterval": "",
 "invoicedToDate": "",
 "operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    }
  ]
}

2.3 Create Recurring-product

Add recurring product on customer level

Request
POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property Data typeFormatRequiredDescription
baseProductCode string MinLength: 1
MaxLength: 5
Regex pattern:"[a-zA-Z0-9]*"		Yes Predefined product ín PayEx Billing system
deviantText string MinLength: 1
MaxLength: 30
Regex pattern:"[a-zA-Z0-9]*"		No Product text, default text from base product
startDate string Type: ISO 8601 Yes Product start date
endDate string Type: ISO 8601 No Product end date
deviantPrice string Type: N(7),N(2-6) No The products price for 1 day
deviantInterval string Type: N(1) No 

Deviant Interval determines how often the invoice is sent.

Default/empty = 1
1,2,3,6 = every 1,2,3,6 month
8 = every 12 months
9 = Stop, no invoice.

The resource is used to add recurring products on customer level

Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "recurringProductId": "4444",
 "operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
    }
  ],
 "@id": "/billing/customer/v1/xxx/customers/224455/recurring-products/4444"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
recurringProductId string  Unique identifier for specific recurrent product
baseProductCode string  Predefined product in PayEx Billing system
deviantText string  Product text, default from base product
startDate string  Product start date
endDate string  Product end date
deviantPrice string  The price of the product, if price is not specified the base product price is used
deviantInterval string  Selected invoicing interval
invoicedToDate string  Date of how long the product has been invoiced (Indicating the date until product has been billed)
operations array  List of operations for this resource. See the documentation for more information. hypermedia part of the response

2.4 Update recurrent line

Some properties on the recurrent line on customer level can be updated through this API. Properties will only be updated if included in the request.

The following recurrent line properties is possible to update through a patch call

Property
endDate

Update recurrent line end date

Request
PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "endDate": "YYYY-MM-DD"
}

3. Subscriptions

Lists subscriptions on customer

3.1 Get list of Subscriptions

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "subscriptionId": "10101010",
     "subscriptionNo": "MF1122334455",
     "name": "Lätt lastbilsförsäkring, ABC123",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "invoiceSeparately": true,
     "deviantCollectionProcess": "",
     "defaultPaymentMethod": true,
     "deviantDistributionMethod": "Email",
     "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products",
     "operations": [
        {
         "rel": "partial-update-subscription",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
        },
        {
         "rel": "add-recurring-product",
         "method": "POST",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
    },
    {
     "subscriptionId": "22101010",
     "subscriptionNo": "CV9988774455",
     "name": "Fritidshusförsäkring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "invoiceSeparately": true,
     "deviantCollectionProcess": "",
     "defaultPaymentMethod": true,
     "deviantDistributionMethod": "Email",
     "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010/recurring-products",
     "operations": [
        {
         "rel": "partial-update-subscription",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010"
        },
        {
         "rel": "add-recurring-product",
         "method": "POST",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010/recurring-products"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/22101010"
    }
  ],
 "navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions"
  }
}

Gets specific subscription

3.2 Get specific Subscription

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "subscriptionId": "10101010",
 "subscriptionNo": "MF1122334455",
 "name": "Lätt lastbilsförsäkring, ABC123",
 "startDate": "YYYY-MM-DD",
 "endDate": "YYYY-MM-DD",
 "invoiceSeparately": true,
 "deviantCollectionProcess": "",
 "defaultPaymentMethod": true,
 "deviantDistributionMethod": "Email",
 "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products",
 "operations": [
    {
     "rel": "partial-update-subscription",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/10101010/recurring-products"
    }
  ]
}

3.3 Create Subscription

Adds subscription

Request
POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property Data typeFormatRequiredDescription
subscriptionNo string MinLength: 1
MaxLength: 34
Regex pattern:"[a-zA-Z0-9]*"		Yes Identifier for subscription
name string MinLength: 1
MaxLength: 100
Regex pattern:"[a-zA-Z0-9]*"		Yes Subscription text for presentation
startDate string Type: ISO 8601 Yes Subscription start date
endDate string Type: ISO 8601 No Subscription end date
invoiceSeparately boolean  NoDefault False=Invoicing on customer level
True=Separate subscription number Invoice
deviantCollectionProcess string  No If used, must be configured with PayEx
defaultPaymentMethod boolean  NoIf True = default payment method in AR, overriding for example "customer direct debit consent"
deviantDistributionMethod string  No "Postal", "Email", overrides customer default/preferred value
Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "subscriptionId": "4444",
 "recurringProducts": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444/recurring-products",
 "operations": [
    {
     "rel": "partial-update-subscription",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444"
    },
    {
     "rel": "add-recurring-product",
     "method": "POST",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444/recurring-products"
    }
  ],
 "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/4444"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
subscriptionId string  Identifier for subscription
subscriptionNo string  Unique identifier for specific subscription
name string  Subscription text for presentation
startDate string  Subscription start date
endDate string  Subscription end date
invoiceSeparately boolean  Default False=Invoicing on customer level
True=Separate subscription number Invoicen
deviantCollectionProcess string  Selected collection process
defaultPaymentMethod boolean  Selected payment method
deviantDistributionMethod string  Selected distributions method
recurringProducts dynamic   Uri for selected subscriptions recurrent lines
operations array  List of operations for this resource. See the documentation for more information. hypermedia part of the response

3.4 Update subscription

Some properties on the subscription can be updated through this API. Properties will only be updated if included in the request.

The following subscription properties is possible to update through a patch call

Property
endDate
invoiceSeparately
deviantCollectionProcess
defaultPaymentMethod
deviantDistributionMethod

Update subscription

Request
PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "endDate": "YYYY-MM-DD",
   "invoiceSeparately": "True/False",
   "deviantCollectionProcess": "Predefined value",
   "defaultPaymentMethod": "True/False",
   "deviantDistributionMethod": "Postal/Email"
}

4. Recurring-products

Lists subscription recurring products

4.1 Get list of Recurring-products

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of subscription recurring products

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "recurringProductId": "5544",
     "baseProductCode": "F01",
     "deviantText": "Fakturaavgift",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "29.000",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    },
    {
     "recurringProductId": "5555",
     "baseProductCode": "P02",
     "deviantText": "Halvforsakring",
     "startDate": "YYYY-MM-DD",
     "endDate": "YYYY-MM-DD",
     "deviantPrice": "",
     "deviantInterval": "",
     "invoicedToDate": "",
     "operations": [
        {
         "rel": "partial-update-recurring-product",
         "method": "PATCH",
         "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5555"
        }
      ],
     "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5555"
    }
  ],
 "navigation": {
   "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products"
  }
}

Gets specific subscription recurring product

4.2 Get specific Recurring-product

Request
GET /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a specific subscription recurring product

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "recurringProductId": "5544",
 "baseProductCode": "F01",
 "deviantText": "Fakturaavgift",
 "startDate": "YYYY-MM-DD",
 "endDate": "YYYY-MM-DD",
 "deviantPrice": "29.000",
 "deviantInterval": "",
 "invoicedToDate": "",
 "operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    }
  ]
}

4.3 Create Recurring-product

Adds subscription recurring product

Request
POST /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Request object specification

Property Data typeFormatRequiredDescription
baseProductCode string MinLength: 1
MaxLength: 5
Regex pattern:"[a-zA-Z0-9]*"		Yes Predefined product in PayEx Billing system
deviantText string MinLength: 1
MaxLength: 30
Regex pattern:"[a-zA-Z0-9]*"		No Product text, default text from base product
startDate string Type: ISO 8601 Yes Product start date
endDate string Type: ISO 8601 No Product end date
deviantPrice string Type: N(7),N(2-6) No The products price for 1 day
deviantInterval string Type: N(1) No 

Deviant Interval determines how often the invoice is sent.

Default = 1
1,2,3,6 = every 1,2,3,6 month
8 = every 12 months
9 = Stop, no invoice.

The resource is used to add a subscription recurring product

Response
HTTP/1.1 201 Created
Content-Type: application/json

{
 "recurringProductId": "5544",
 "operations": [
    {
     "rel": "partial-update-recurring-product",
     "method": "PATCH",
     "href": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
    }
  ],
 "@id": "/billing/customer/v1/xxx/customers/224455/subscriptions/2010101010/recurring-products/5544"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
recurringProductId string  Unique identifier for specific recurrent product
baseProductCode string  Predefined product in PayEx Billing system
deviantText string  Product text, default from base product
startDate string  Product start date
endDate string  Product end date
deviantPrice string  The price of the product, if price is not specified the base product price is used
deviantInterval string  Selected invoicing interval
invoicedToDate string  Date of how long the product has been invoiced (Indicating the date until product has been billed)
operations array  List of operations for this resource. See the documentation for more information. hypermedia part of the response

4.4 Update recurrent line

Some properties on the recurrent line can be updated through this API. Properties will only be updated if included in the request.

The following recurrent line properties is possible to update through a patch call

Property
endDate

Update recurrent line end date

Request
PATCH /billing/customer/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionId}/recurring-products/{recurringProductId} HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "endDate": "YYYY-MM-DD"
}

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Response
HTTP/1.1 400 Error
Content-Type: application/problem+json

{
  "Type" : "ledger/{domain}/v1/problems/validation",
  "Title" : "A validation error occurred",
  "Status" : 400,
  "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
  "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
  "Problems" :
      {
        "amount" : [
           "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
         ]
      }
}

Problem types

Note, each problem typecode is preceded by "billing/invoice/service" in this API, e.g. the error "validation" in the table below will appear as typecode "billing/invoice/problems/validation".

Problem type (code)Http statusDescription
validation400occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
customer-not-found404Customer not found in PayEx Billing
invoice-not-found404

Invoice number not found in Usage

subscription-not-found404Subscription not found on selected customer
Created by Anders Göthberg on 2026/05/13 09:54