Skip to main content

AccountingPeriod

Zuora

AccountingPeriod

Use the AccountingPeriod object to create accounting periods. This reference describes the SOAP API object including supported calls, required permissions,  and field descriptions. Examples are also provided.

Accounting Periods

Accounting periods match your financial periods. Zuora aligns your transactions to your accounting periods, and shows you the history of how your business performs across multiple accounting periods. An accounting period holds the information you need to perform your company's bookkeeping activities, especially tracking and reporting financial activities such as earnings, expenses, and taxes. You create accounting periods in Z-Finance to encompass the financial transactions during your company's accounting period, then close the accounting period per your company's specified time. Closing an accounting period in Zuora is like closing the books.

You create accounting periods to close the books and report on financial activities.

Supported Calls

You can use this object with the following calls:

Permissions

Access to Z-Finance is required for all interactions.

You need the Create Accounting Period permission to update the following fields:

  • Name
  • StartDate
  • EndDate
  • Notes
  • FiscalYear
  • CustomFields

You need the Manage Close Process and Run Trial Balance permissions to update the Status field value from Open to Closed.

You need the Reopen Accounting Period permission to reopen an accounting period, which updates the Status field value from Closed to Open.

You need the Delete Accounting Period permission to delete an accounting code.

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name Required to Create? Allowed
Operations
Description

CreatedById

Optional

Query

The identifier of the user who created the accounting code.

Type: string ID

Character limit: N/A

Version: WSDL 50.0+

Z-Finance RequiredNo

CreatedDate

Optional

Query

The date when the accounting code was created.

Type: dateTime

Character limit: N/A

Version: WSDL 50.0+

Z-Finance RequiredNo

EndDate required

Create
Query
Update
Filter

The end date of the accounting period.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit

Version notes: Z-Finance

FiscalQuarter optional Create
Query
Update
Filter

The fiscal quarter of the accounting period.

Type: int

Character limit:

Version notes: WSDL 81.0+

Values: The default value is null. Supported values are: 1, 2, 3, and 4.

FiscalYear required Create
Query
Update
Filter

The fiscal year for the accounting period.

Type: int

Character limit:

Version notes: Z-Finance

Values: a valid integer of the form, YYYY

Id optional Query
Filter

The ID of this object. Upon creation of this object, this field becomes AccountingPeriodId.

Type: zns:ID

Character limit: 32

Version notes: --

Values: automatically generated

Name required Create
Query
Update
Filter

The name of the accounting period, which is displayed on the list of accounting periods on the All Accounting Periods page.

Type: string

Character limit:100

Version notes: Z-Finance

Values: a string of 100 characters or fewer

Notes optional Create
Query
Update
Filter
Use this field to record comments about the accounting period.

Type: string

Character limit: 255

Version notes: Z-Finance

Values: a string of 255 characters or fewer

Status required

Query
Update
Filter

The status of the accounting period.

Type: string

Character limit: 6

Version notes: Z-Finance

Allowable values: automatically generated on creattion; one of the following values:

  • Open
  • Closed
StartDate required Create
Query
Update
Filter

The start date of the accounting period.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: Z-Finance

Values: automatically generated after the first accounting period

UpdatedById

Optional

Query

The identifier of the user who created the accounting code.

Type: string ID

Character limit: N/A

Version: WSDL 50.0+

Z-Finance Required: No

UpdatedDate

Optional

Query

The date when the accounting code was updated.

Type: dateTime

Character limit: N/A

Version: WSDL 50.0+

Z-Finance RequiredNo

Additional Field Detail

EndDate

You can update the end date only for your open accounting periods.

When you update the end date of an accounting period, then the start date of the next accounting period is automatically updated to the day after the new end date. For example:

The accounting period, August 2012, starts on 08/01/2012 and ends on 08/30/2012. The accounting period, September 2012, starts on 08/31/2012 and ends on 09/29/2012. You change the end date of August 2012 to 08/31/2012. The start date of September 2012 automatically changes to 09/01/2012.

Any existing trial balance results are removed when you alter the dates of accounting periods.

The accounting period history is updated when you change it. If you change dates, then the history of the accounting period you edited and the histories of the accounting periods that automatically change are also updated.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscriptionobject's ID with the call.

The ID for the AccountingPeriod object is AccountingPeriodId.

StartDate

You can update the start date only for your first accounting period. The StartDate field is available to you only the first time the very first accounting period is created. After the first accounting period is created, subsequent accounting periods automatically start the day after the most recent end date.

Status

The status of the accounting period is automatically generated as Open when you create an accounting period.

When you run a query() call against the Status field, the value can be one of the following:

  • Open: The accounting period is open, and transactions can be recorded in the period. A new accounting period always starts in Open status.
  • Closed: The accounting period is locked down. You can change only the values in the Name, Notes, and FiscalYear fields. To make any other changes, you must reopen the accounting period.

An API call that updates the Status field cannot update any other fields.

Examples

Create an accounting period

AccountingPeriod ap = new AccountingPeriod();
ap.setName(AP_NAME);
ap.setStartDate(startDate);
ap.setEndDate(endDate);
ap.setNotes(AP_NOTES);
ap.setFiscalYear(YEAR);
create(ap);

Create an accounting period using a SOAP wrapper


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.zuora.com/" xmlns:obj="http://object.api.zuora.com/">
   <soapenv:Header>
      <api:SessionHeader>
         <api:session>{replace with your session}</api:session>
      </api:SessionHeader>
      <api:CallOptions>
         <!--Optional:-->
         <api:useSingleTransaction>?</api:useSingleTransaction>
      </api:CallOptions>
   </soapenv:Header>
   <soapenv:Body>
     <ns1:create xmlns:ns1="http://api.zuora.com/">
<ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
<ns2:Name>apFromAPI16</ns2:Name>
<ns2:StartDate>2011-08-10</ns2:StartDate>
<ns2:EndDate>2011-08-10</ns2:EndDate>
<ns2:Notes>ap notes from api</ns2:Notes>
<ns2:FiscalYear>2011</ns2:FiscalYear>
<ns2:FiscalQuarter>3</ns2FiscalQuarter>
</ns1:zObjects>
</ns1:create>
   </soapenv:Body>
</soapenv:Envelope>

Query an accounting period

String zql = "select EndDate, Name, Notes, Status, StartDate, FiscalYear from AccountingPeriod where id = '402892a133d3ff8b0133d4bf63070022'";
AccountingPeriod ap = (AccountingPeriod) queryOne(zql);

Query an accounting period with a SOAP wrapper

<?xml version="1.0" encoding="http://schemas.xmlsoap.org/soap/envelope/" standalone="no"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>{replace with your session}</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:query xmlns:ns1="http://api.zuora.com/">
            <ns1:queryString>
            select id, CreatedById, CreatedDate, EndDate, Name, Notes, Status, StartDate, UpdatedById, UpdatedDate, FiscalYear, FiscalQuarter from AccountingPeriod where id = ' 4028929f33ca990b0133ca9ed8400002'
            </ns1:queryString>
        </ns1:query>
    </soapenv:Body>
</soapenv:Envelope>

Updating an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
                <ns2:Id>402892a837113da60137113ee28901a9</ns2:Id>
            <ns2:EndDate>2012-02-15</ns2:EndDate>
            <ns2:FiscalYear>2013</ns2:FiscalYear>
            <ns2:FiscalQuarter>1</ns2FiscalQuarter>
            <ns2:Name>update name</ns2:Name>
            <ns2:Notes>update notes</ns2:Notes>
            <ns2:StartDate>2012-01-15</ns2:StartDate>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>

Closing an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
            <ns2:Id>402892a83711418b01371142cc5801a9</ns2:Id>
            <ns2:Status>Closed</ns2:Status>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>

Reopening an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
        </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
            <ns2:Id>402892a83711442701371145625d01a9</ns2:Id>
            <ns2:Status>Open</ns2:Status>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>