Invoice

Manage Invoices.

Show Invoice

GET https://app.clubcollect.com/api/v2/invoices/:id

Fetch Invoice details.

Path Parameters

NameTypeDescription

id*

string

Invoice ID

Query Parameters

NameTypeDescription

api:key

string

Partner API Key (Deprecated)

Headers

NameTypeDescription

Authorization*

string

ApiKey <api_key>

Content-Type

string

Must be application/json.

{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },        
    {
      "invoice_line_id": "...",           
      "type": "CREDIT-LINE",            
      "amount_cents": -1000,           
      "description": "Deduction",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "CHARGEBACK-LINE",            
      "amount_cents": 123,           
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",           
      "type": "CHARGEBACK-FEE-LINE",            
      "amount_cents": 123,           
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "CHARGEBACK-FEE-PAYMENT-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "LATE-PAYMENT-FEE-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "LATE-PAYMENT-FEE-PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "INSTALLMENT-FEE-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "INSTALLMENT-FEE-PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    }    
  ],
  "amount_total_cents": "...",
  "messages": [
    {
      "message_id": "...",
      "type": "EMAIL|SMS|LETTER",
      "description": "...",
      "date": "..."
    },
    {
      "message_id": "...",
      "type": "EMAIL|SMS|LETTER",
      "description": "...",
      "date": "..."}
  ],
  "tickets": [
    {
      "ticket_id": "...",
      "message": "I don't want to pay",
      "sender": "CUSTOMER",
      "date": "..."
    },
    {
      "ticket_id": "...",
      "message": "You really must pay",
      "sender": "COMPANY",
      "date": "..."}
  ],
  "retracted_at": null | "...",
  "retraction_reason": null | "...",
  "show_retraction_reason_to_customer": true | false
}

Note the date format is ISO 8601.

Note a Partner usually calls the GET /v2/invoices/:id method in response to a notification sent by ClubCollect about an update to an Invoice.

Note To get a list of possible values for invoice lines types see the Invoice Line documentation.

Create Invoice

POST https://app.clubcollect.com/api/v2/invoices

Create an Invoice with one or more Invoice Lines.

Query Parameters

NameTypeDescription

api:key

string

Partner API Key (Deprecated)

Headers

NameTypeDescription

Authorization*

string

ApiKey <api_key>

Content-Type*

string

Must be: application/json.

Request Body

NameTypeDescription

locale

string

When supplied, the invoice's locale will be set to this value. From { de en fr it nl }

direct:debit:iban

string

When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.

federation:membership:number

string

club:membership:number

string

member:external:id

string

external:membership:number

string

invoice:lines[].invoice:line:id

string

Optionally specify a custom identifier to overwrite an otherwise randomly generated identifier. If given, the partner must ensure that the ID is unique. Requests with duplicate IDs will be rejected.

amount:total:cents*

number

Must be equal to the sum of the amounts of the Invoice Lines. May be zero or negative.

invoice:lines*

array

customer.address.country:code*

string

May be empty if `email_address` or `phone_number` is provided

customer.address.city*

string

May be empty if `email_address` or `phone_number` is provided

customer.address.zipcode*

string

May be empty if `email_address` or `phone_number` is provided

customer.address.address1*

string

May be empty if `email_address` or `phone_number` is provided

customer.address.address2

string

customer.address.house:number

string

customer.address.house:number:extension

string

customer.address.locality

string

customer.address.state

string

customer.phone.country:code*

string

May be empty if `email_address` or a postal address is provided

customer.phone.phone:number*

string

May be empty if `email_address` or a postal address is provided

customer.email.email:address*

string

May be empty if `phone_number` or a postal address is provided

customer.name.prefix

string

customer.name.first:name

string

customer.name.infix

string

customer.name.last:name*

string

customer.name.organization

string

external:invoice:number*

string

reference

string

import:id*

string

ID of Import to which the Invoice should belong.

{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}

Example Request Body

{
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "locale": "en",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000
}

Error Messages

  • invalid_import_id: No import with this ID could be found.

  • invalid_external_invoice_number: formatting error: min. 1 character.

  • invalid_customer_last_name: Last name may not be empty.

  • invalid_customer_email: Email address may not be empty if no phone number is provided.

  • invalid_customer_phone: Phone number may not be empty if no email address is provided.

  • invalid_customer_address: Address may not be empty if neither an email address nor phone number is provided.

  • invalid_amount_total_cents: amount_total_cents is not equal to the total of all invoice line amounts.

  • duplicate_invoice_line_id: The duplicate_invoice_line_id provided was already used for another invoice line.

  • invalid_content_type: Content-Type: application/json must be provided.

Note the total may be zero (nothing to receive) or negative (something to receive).

Note at least one of:

  • customer.email.email_address

  • customer.phone.*

  • customer.address.*

must be provided. i.e. there must be a way for us to contact the Customer via email, phone or postal mail.

Note It's not possible to add or delete invoice lines for an existing invoice. If an invoice is incorrectly created with a wrong amount outstanding (or the invoice becomes invalid for some reason after it's transmitted), the partner can credit it using /credit_and_retract endpoint.

Update Invoice

PUT https://app.clubcollect.com/api/v2/invoices/:id

Update a subset of Invoice attributes.

Note The invoice lines can't be updated, only the attributes relative to the recipient of the invoice can be updated.

Path Parameters

NameTypeDescription

id*

string

Invoice ID

Query Parameters

NameTypeDescription

api:key

string

Partner API Key (Deprecated)

Headers

NameTypeDescription

Authorization*

string

ApiKey <api_key>

Content-Type*

string

Must be: application/json.

Request Body

NameTypeDescription

locale

string

When supplied, the invoice's locale will be set to this value. From { de en fr it nl }

direct:debit:iban

string

When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.

federation:membership:number

string

club:membership:number

string

member:external:id

string

external:membership:number

string

customer.address.country:code

string

customer.address.city

string

customer.address.zipcode

string

customer.address.address1

string

customer.address.address2

string

customer.address.house:number

string

customer.address.house:number:extension

string

customer.address.locality

string

customer.address.state

string

customer.phone.country:code

string

customer.phone.phone:number

string

customer.email.email:address

string

customer.name.last:name

string

customer.name.organization

string

external:invoice:number*

string

reference

string

{
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}

Example Request Body

{
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
}

Error Messages

  • invalid_invoice_id: No invoice with this invoice_id could be found.

  • invalid_external_invoice_number: formatting error: min. 1 character.

  • invalid_customer_last_name: Last name may not be empty.

  • invalid_customer_email: Email address may not be empty if no phone number is provided.

  • invalid_customer_phone: Phone number may not be empty if no email address is provided.

  • invalid_content_type: Content-Type: application/json must be provided.

Credit and Retract Invoice

POST https://app.clubcollect.com/api/v2/invoices/:id/credit:and:retract

Call this method to credit the total outstanding amount of an invoice and retract it in a single HTTP request. Any payment decision made for the invoice will be cancelled. Additional fees that might be due will be credited automatically. It won't be possible to apply more credits to the invoice.

Path Parameters

NameTypeDescription

id*

string

ID of the Invoice to be retracted.

Query Parameters

NameTypeDescription

api:key

string

Partner API Key (Deprecated)

Headers

NameTypeDescription

Authorization*

string

ApiKey <api_key>

Content-Type*

string

Must be application/json.

Request Body

NameTypeDescription

show:retraction:reason:to:customer

boolean

external:invoice:number*

string

retraction:reason

string

description*

string

{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}

Example Request Body

{
  "external_invoice_number": "2014-342-545",
  "description": "Cash payment",
  "retraction_reason": "Paid by cash",
  "show_retraction_reason_to_customer": true
}

Error Messages

  • invalid_invoice_id: No invoice with this ID could be found.

  • invalid_external_invoice_number: min. 1 character

  • invalid_description: description must be provided.

  • already_retracted: The invoice with this ID has already been retracted.

  • invalid_content_type: Content-Type: application/json must be provided.

  • payment_in_progress: An invoice can't be credited or retracted if there's a payment in progress

Delete Invoice

DELETE https://app.clubcollect.com/api/v2/invoices/:id

Deletes an invoice. Deleting an invoice is possible only when it's not transmitted yet.

Path Parameters

NameTypeDescription

id*

string

Invoice ID

Query Parameters

NameTypeDescription

api:key

string

Partner API Key (Deprecated)

Headers

NameTypeDescription

Authorization*

string

ApiKey <api_key>

Last updated