Invoices

Sivo Advance enables marketplace platforms to offer invoice factoring and cash advances to sellers. This guide provides a high-level overview of implementing Sivo Advance in your platform.

---
config:
  theme: redux
---
sequenceDiagram
    actor B as Buyer
    actor S as Seller
    participant P as Platform
    participant Sivo as Sivo Advance

    B ->> P: Upload POD
    P ->> S: Notify of POD and offer advance
    S ->> Sivo: Request advance on invoice
    Sivo ->> S: Response with advance amount
    S ->> Sivo: Accept advance terms
    Sivo --) P: Disburse advance funds<br/>(minus Sivo, Platform fees<br/>and reserve)
    P --) S: Deliver advance to seller
    activate P
    Note over P: Wait for payment
    B --) P: Pay Invoice
    deactivate P
    P --) Sivo: Send funds (minus Platform fees)
    opt if needed
        Sivo--) P: Send remaining reserve
        P--) S: Send remaining reserve
    end

Implementation Workflow

1. Create Seller

First, register the seller entity that will receive the advance. Provide comprehensive details to facilitate underwriting.

POST /accounts

Required details typically include:

• Legal entity information
• Business address
• Contact information
• Banking details for disbursement
• For underwriting:
  • Date when seller first became active in the platform
  • KYX status
  • Annual revenue in USD
  • Performance score
  • Buyer concentration

2. Create Buyer

Register the buyer that will be invoiced and eventually pay the seller.

POST /accounts

Important buyer information includes:

• Legal entity information
• Business address
• Contact information
• For underwriting:
  • Shipping address
  • Legal entity ID: DUNS
  • PAYDEX score
  • KYX status
  • Average days to pay
  • Lifetime spend in USD

3. Create Supplier (Optional)

POST /accounts

Required details typically include:

• Legal entity information
• Business address
• Contact information
• Banking details for disbursement
• For underwriting (tentative as of 2025-07-25):
  • Date when seller first became active in the platform
  • KYX status
  • Annual revenue in USD
  • Performance score
  • Buyer concentration

4. Create Invoice

After a seller completes work for a buyer, create an invoice in the system.

POST /sellers/{seller_id}/invoices

The invoice should include:

• Invoice number/identifier
• Invoice date
• Payment terms (e.g., Net 30)
• Total amount due
• Buyer reference
• Supplier reference

5. Add Invoice Items

Add detailed line items to the invoice to provide transparency about what's being billed.

POST /sellers/{seller_id}/invoices/{invoice_id}/invoiceitems

Each item should specify:

• Description of goods/services
• Quantity
• Unit price
• Total amount

6. Request Terms for Advance

When a seller wants an advance on their invoice, generate the advance terms.

POST /sellers/{seller_id}/invoices/{id}/terms/generate

The response will include the amount to be advanced, the transfer amount, and the expected payment date.

7. Accept Advance Terms

If the seller accepts the terms, submit their acceptance to initiate the advance.

POST /sellers/{seller_id}/invoices/{id}/terms/accept

This step triggers the disbursement of funds

8. Get Advance Balances and Ledgers

GET /sellers/{seller_id}/invoices/{id}/terms/transactions
GET /sellers/{seller_id}/invoices/{id}/terms/balances

To check the status of an advance you can access the balances and ledgers. They include the following:

• Payout transactions: details of advance disbursement from Sivo to your bank.
• Payin transactions: details about expected payments to Sivo, including amount and due date. Received payments will also appear when they are received.
• Reserve transactions: if your advance has a reserve you can verify its balance and associated details.

9. Send Payment to Sivo

The platform continues to manage the invoice collection process with the buyer. When payment is received, the platform sends the expected payment to Sivo. Include the sivo invoice id as the payment reference.

10. Receive Reserve (if applicable)

If there is remaining reserve to be returned, Sivo will transfer it back to the platform which can then distribute it to the seller.

Best Practices

1. Comprehensive Data Collection: Provide as much data as possible when creating buyers and sellers to improve underwriting.

2. Accurate Data: Provide complete and correct data to ensure accurate advance calculations.

3. Clear Communication: Ensure sellers understand the advance terms, including fees and reserve calculations.

For detailed API specifications, see the API Reference.