This guide will walk you through sending your first invoice with Auction Studio. In this example, we'll be invoicing your customer for a few various things and send that invoice for them to pay.
To successfully complete the tutorial, you need to do the following:
To start, we'll need to start tracking transactions and assigning them to customers. Auction Studio is made to be easy to use out of the box, not requiring you to maintain state on your side (unless you want to). We will be using External IDs to help keep track of your customers. As you'll see them, you can use them in place of keeping track of our unique customer IDs (i.e. cus_1a2b3c4d5e). In this example, I assume that you have a customer with
id = 483
,
but this could be any number or string that you use to uniquely identify your customer.
Once you create a transaction, if a customer with the supplied external ID does not exist, we'll create one for you. Later on we will make sure we identify that customer so they can be properly invoiced.
curl https://api.paidlabs.com/v0/transactions \ -u {YOUR API KEY}: \ -d external_id=483 \ -d amount=9743 \ -d "description=Designing awesome holiday cards."
{ "id": "tr_3fj38099dalkxie", "object": "transaction", "amount": 9743, "currency": "usd", "description": "Designing awesome holiday cards.", "customer": "cus_DLjf9aDKE9fkdncz", "paid": false, "paid_at": null, "invoice": null }
Now that we have our first transaction, let's add another one just to see how powerful Auction Studio really is. You can think of transactions as line items on an invoice. Any time you have an amount you want from someone, whether it be immediately or to be invoiced later, you track that transaction with us.
Notice that we are also using the same External ID to create the transaction. This will ensure that the transaction is assigned to the same customer without you having to manage Auction Studio identifiers. You could have also passed in
customer = cus_DLjf9aDKE9fkdncz
,
which you could get from the response of creating our first transation.
curl https://api.paidlabs.com/v0/transactions \ -u {YOUR API KEY}: \ -d external_id=483 \ -d amount=15000 \ -d "description=Platform Fee - Standard Package"
{ "id": "tr_3fj38099dalkxie", "object": "transaction", "amount": 15000, "currency": "usd", "description": "Platform Fee - Standard Package", "customer": "cus_DLjf9aDKE9fkdncz", "paid": false, "paid_at": null, "invoice": null }
Great! We have a couple transactions (or more if you are an overachiever), so now we need to generate an invoice. Auction Studio takes care of ensuring all uninvoiced and unpaid transactions are put on the next invoice. All you need to do is trigger the generation of an invoice, either manually or by setting up the customer on a regular billing cycle (see our other guide for invoice automation).
curl https://api.paidlabs.com/v0/customers/by_external_id/generate_invoice?external_id=483 \ -u {YOUR API KEY}: \ -X POST
{ "object": "invoice", "id": "inv_8KAu1BU4PiY49XtN0A", "summary": null, "next_reminder_on": null, "terms": 30, "customer": "cus_DLjf9aDKE9fkdncz", "issued_at": null, "paid": false, "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiY49XtN0A" }
Before we can issue the invoice, Auction Studio needs to know the name and email for the customer. To carry on with our theme of using External IDs, we'll update the customer using that.
curl https://api.paidlabs.com/v0/customers/by_external_id?external_id=483 \ -u {YOUR API KEY}: \ -d "name=Ryan Jackson" \ -d "email=hello@paidlabs.com" \ -X POST
{ "id": "cus_DLjf9aDKE9ueDncz", "object": "customer", "name": "Paid", "email": "hello@paidlabs.com", "external_id": "483", "description": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "phone": null, "allow_ach": true, "allow_check": true, "allow_credit_card": true, "allow_wire": true, "terms": 30, "billing_type": "invoice", "billing_cycle": "manual", "stripe_customer_id": null }
curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiY49XtN0A/issue \ -u {YOUR API KEY}: \ -X POST
{ "object": "invoice", "id": "inv_8KAu1BU4PiY49XtN0A", "summary": null, "next_reminder_on": null, "terms": 30, "customer": "cus_DLjf9aDKE9fkdncz", "issued_at": 1424607219, "paid": false, "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiY49XtN0A" }
If you've edited your account to enable at least one payment method, you'll see that option at the bottom of the invoice. Click it to pay the invoice. If you've chosen to allow Credit Cards, we will automatically mark the invoice as paid when the transaction is successful. Other methods have a delay from when the payment is sent and received, so you will need to view the invoice in your dashboard to reconcile the payment.