Invoice

Manage Invoices.
get
Show Invoice
https://api.clubcollect.com/api/v2/invoices/:id
Fetch Invoice details.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Headers
Content-Type
optional
string
Must be application/json.
Query Parameters
api_key
required
string
Partner API Key
Response
200: OK
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_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
}
404: Not Found
{
  "error": "invalid_invoice_id"
}
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.
post
Create Invoice
https://api.clubcollect.com/api/v2/invoices
Create an Invoice with one or more Invoice Lines.
Request
Response
Request
Headers
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
Body Parameters
locale
optional
string
When supplied, the invoice's locale will be set to this value. From { de en fr it nl }
direct_debit_iban
optional
string
When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.
federation_membership_number
optional
string
​
club_membership_number
optional
string
​
invoice_lines[].invoice_line_id
optional
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
required
number
Must be equal to the sum of the amounts of the Invoice Lines. May be zero or negative.
invoice_lines
required
array
​
customer.address.country_code
required
string
​
customer.address.city
required
string
May be empty if `email_address` or `phone_number` is provided`
customer.address.zipcode
required
string
May be empty if `email_address` or `phone_number` is provided`
customer.address.address1
required
string
May be empty if `email_address` or `phone_number` is provided`
customer.address.address2
optional
string
​
customer.address.house_number
optional
string
​
customer.address.house_number_extension
optional
string
​
customer.address.locality
optional
string
​
customer.address.state
optional
string
​
customer.phone.country_code
required
string
May be empty if `email_address` or a postal address is provided`
customer.phone.phone_number
required
string
May be empty if `email_address` or a postal address is provided.
customer.email.email_address
required
string
May be empty if `phone_number` or a postal address is provided.
customer.name.last_name
required
string
​
customer.name.organization
optional
string
​
external_invoice_number
required
string
​
reference
optional
string
​
import_id
required
string
ID of Import to which the Invoice should belong.
Response
200: OK
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_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": "...",
  "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.
put
Update Invoice
https://api.clubcollect.com/api/v2/invoices/:id
Update a subset of Invoice attributes.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Headers
Content-Type
required
string
Must be: application/json.
Query Parameters
api_key
required
string
Partner API Key
Body Parameters
locale
optional
string
When supplied, the invoice's locale will be set to this value. From { de en fr it nl }
direct_debit_iban
optional
string
When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.
federation_membership_number
optional
string
​
club_membership_number
optional
string
​
customer.address.country_code
optional
string
​
customer.address.city
optional
string
​
customer.address.zipcode
optional
string
​
customer.address.address1
optional
string
​
customer.address.address2
optional
string
​
customer.address.house_number
optional
string
​
customer.address.house_number_extension
optional
string
​
customer.address.locality
optional
string
​
customer.address.state
optional
string
​
customer.phone.country_code
optional
string
​
customer.phone.phone_number
optional
string
​
customer.email.email_address
optional
string
​
customer.name.last_name
optional
string
​
customer.name.organization
optional
string
​
external_invoice_number
required
string
​
reference
optional
string
​
Response
200: OK
{
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_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": []
}
404: Not Found
{
  "error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
  "error": "invalid_external_invoice_number"
}
Example Request Body
{
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_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.
post
Credit and Retract Invoice
https://api.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.
Request
Response
Request
Path Parameters
id
required
string
ID of the Invoice to be retracted.
Headers
Content-Type
required
string
Must be application/json.
Query Parameters
api_key
required
string
Partner API Key.
Body Parameters
show_retraction_reason_to_customer
optional
boolean
​
external_invoice_number
required
string
​
retraction_reason
optional
string
​
description
required
string
​
Response
200: OK
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_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": []
}
404: Not Found
{
  "error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
  "error": "payment_in_progress"
}
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
Delete Invoice
https://api.clubcollect.com/api/v2/invoices/:id
Deletes an invoice. Deleting an invoice is possible only when it's not transmitted yet.
Request
Response
Request
Path Parameters
id
required
string
Invoice ID
Query Parameters
api_key
required
string
Partner API Key
Response
204: No Content
Invoice successfully deleted.
​
404: Not Found
{
  "error": "invalid_invoice_id"
}
422: Unprocessable Entity
{
  "error": "invoice_already_transmitted"
}