Getting Started

Getting Started with Auction Studio


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.


Before You Start

To successfully complete the tutorial, you need to do the following:

  • Sign up for a Auction Studio account and your Test Key will be loaded into the samples below. When you're ready to invoice and receive real money, remember to switch to your Live API key.
  • Edit your account to enable different payment methods. Fill out the appropriate fields to allow ACH, Wire, Credit Card and Check payments.

Select your preferred language for the tutorial:

Step 1: Create First Transaction

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.

First Transaction

curl https://api.paidlabs.com/v0/transactions \
  -u  {YOUR API KEY}: \
  -d external_id=483 \
  -d amount=9743 \
  -d "description=Designing awesome holiday cards."

First Transaction Response

{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 9743,
  "currency": "usd",
  "description": "Designing awesome holiday cards.",
  "customer": "cus_DLjf9aDKE9fkdncz",
  "paid": false,
  "paid_at": null,
  "invoice": null
}

Step 2: Another Transaction

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.

Second Transaction

curl https://api.paidlabs.com/v0/transactions \
  -u  {YOUR API KEY}: \
  -d external_id=483 \
  -d amount=15000 \
  -d "description=Platform Fee - Standard Package"

Second Transaction Response

{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 15000,
  "currency": "usd",
  "description": "Platform Fee - Standard Package",
  "customer": "cus_DLjf9aDKE9fkdncz",
  "paid": false,
  "paid_at": null,
  "invoice": null
}

Step 3: Generate an Invoice

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).

Generate an Invoice

curl https://api.paidlabs.com/v0/customers/by_external_id/generate_invoice?external_id=483 \
   -u {YOUR API KEY}: \
   -X POST

Generate an Invoice Response

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

Step 4: Add Customer Contact Info

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.

Update Customer

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

Update Customer Response

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

Step 5: Issue the Invoice

Issue the Invoice

curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiY49XtN0A/issue \
   -u {YOUR API KEY}: \
   -X POST

Issue the Invoice Response

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

Bonus: Reconcile the Invoice

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.

Congratulations! You've created your first invoice. Now check out the next tutorial to set up automatic invoicing using Billing Cycles.
Billing Cycles Guide