Invoice

Manage Invoices.

Show Invoice

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

Fetch Invoice details.

Path Parameters

Name	Type	Description
id*	string	Invoice ID

Query Parameters

Name	Type	Description
api:key	string	Partner API Key (Deprecated)

Headers

Name	Type	Description
Authorization*	string	ApiKey <api_key>
Content-Type	string	Must be application/json.

200

{
  "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": "[e-mail]"
    },
    "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

{
  "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.

Create Invoice

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

Create an Invoice with one or more Invoice Lines.

Query Parameters

Name	Type	Description
api:key	string	Partner API Key (Deprecated)

Headers

Name	Type	Description
Authorization*	string	ApiKey <api_key>
Content-Type*	string	Must be: application/json.

Request Body

Name	Type	Description
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.

200

{
  "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": "[e-mail]"
    },
    "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": "[e-mail]"
    },
    "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

Name	Type	Description
id*	string	Invoice ID

Query Parameters

Name	Type	Description
api:key	string	Partner API Key (Deprecated)

Headers

Name	Type	Description
Authorization*	string	ApiKey <api_key>
Content-Type*	string	Must be: application/json.

Request Body

Name	Type	Description
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

200

{
  "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": "[e-mail]"
    },
    "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

{
  "error": "invalid_invoice_id"
}

422

{
  "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": "...",
  "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": "[e-mail]"
    },
    "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

Name	Type	Description
id*	string	ID of the Invoice to be retracted.

Query Parameters

Name	Type	Description
api:key	string	Partner API Key (Deprecated)

Headers

Name	Type	Description
Authorization*	string	ApiKey <api_key>
Content-Type*	string	Must be application/json.

Request Body

Name	Type	Description
show:retraction:reason:to:customer	boolean
external:invoice:number*	string
retraction:reason	string
description*	string

200

{
  "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": "[e-mail]"
    },
    "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

{
  "error": "invalid_invoice_id"
}

422

{
  "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 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

Name	Type	Description
id*	string	Invoice ID

Query Parameters

Name	Type	Description
api:key	string	Partner API Key (Deprecated)

Headers

Name	Type	Description
Authorization*	string	ApiKey <api_key>

204

404

{
  "error": "invalid_invoice_id"
}

422

{
  "error": "invoice_already_transmitted"
}