Invoice

Manage Invoices.

PreviousImport NextInvoice Line

Last updated 2 years ago

Show Invoice

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

Fetch Invoice details.

Path Parameters

Name

Type

Description

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

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

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

Headers

Request Body

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

Query Parameters

Headers

Request Body

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

{
  "error": "invalid_invoice_id"
}

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

Query Parameters

Headers

Request Body

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

{
  "error": "invalid_invoice_id"
}

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

Query Parameters

Headers

{
  "error": "invalid_invoice_id"
}

{
  "error": "invoice_already_transmitted"
}